Page Agent Sdk

page-agent-sdk

> English · 中文

> Give your web page an AI assistant that edits the page itself. Mount a chat dialog in one line; the AI reads/writes page data safely via schema-validated tools — "conversational" building/editing/ops. A lighter, framework-agnostic alternative to CopilotKit / LangChain for in-page, schema-validated JSON-editing agents.

> AI agent integration: see [Agent Integration Cheat Sheet](#agent-integration-cheat-sheet-for-ai-agents) below (exports / options / extension points / built-in tools / file structure). Architecture & gotchas in CLAUDE.md.

[](https://www.npmjs.com/package/page-agent-sdk) [](https://github.com/whyymj/page-agent-sdk/blob/master/LICENSE) [](#self-tests)

---

> 🚀 Quick start? → [30-second quickstart](#30-second-quickstart) · [Examples](#examples) · [Options cheat sheet](#createchatsdk-options-cheat-sheet) · [LLM 连接](#llm-连接直连--代理--openai-兼容端点)

Who is it for

Low-code / visual builders, form & page designers, CMS, ops consoles — anywhere "page data is structured, and you want natural language to drive it".

One-line gist: declare the page data structure (schema) to the Agent; it reads/writes via tools, validated by schema — "editing the page" goes from drag/fill to a single sentence.

What it is: a standardized JSON-operation Agent

At its core, it gives the AI a standardized, safe JSON-operation channel. AI editing JSON is no longer "generate a blob of text and stuff it back" (uncontrolled), but a structured operation under four constraints:

| Constraint | Mechanism | Effect | |---|---|---| | Scope control | Declared schema fields (data) — only declared keys are writable; schema shape auto-whitelist (top-level + sub-path recursively projected by sub-schema; undeclared fields hidden/denied; whole-set becomes merge to prevent accidental deletion; interceptors.write-supplied invisible fields persisted) | AI touching undeclared fields → PATH_DENIED | | Validity check | zod schema — write/set/edit validated against schema | Invalid type/enum/structure → structured error, no write | | Incremental op | write with patch/patches (batch, atomic rollback) or advanced edit_data patches by jsonPath (set/remove/merge/append) | Avoid re-sending the whole large JSON; precise local edits; use patches to edit many at once | | Large-object retrieval | read supports fields (projection) + depth (truncation) to shrink payload; query_data (JSONPath)/search_data (text)/eval_script (sandboxed JS) | Efficient retrieval + pinpoint location in large JSON | | Rollbackable | per-path snapshots (auto-stacked) + session checkpoint | Bad edit → one-click restore to the last good state | | Optimistic lock | expectedHash on set/edit/delete + conflict human-in-the-loop | Concurrent external edits detected → suspend, user picks keep/overwrite/restore |

"Editing JSON" moves from free-form LLM text generation to structured, validatable, auditable, rollbackable tool operations. This is the fundamental difference from "let the AI output a JSON string directly".

Use cases

| Scenario | User says | AI does | |---|---|---| | 🏗 Low-code builder | "Top banner → dark, bold the title, add a new-product card" | Incremental patch the component tree via jsonPath; canvas refreshes live | | 📝 Form designer | "Add phone format validation, address → 3-level cascade" | Incremental field-definition edits, schema-validated | | 📰 CMS ops | "Prefix these products with 'Limited', mark under ¥100 red" | JSONPath filter + sandbox script batch edit | | 🖥 Ops console | "Raise A's threshold to 30%, turn off switch B" | Whitelist + human-confirm to edit config, read-back verify | | 🤖 AI-native assistant | "Change this chart's legend to bars" | Conversational ops on product data, no UI needed | | 🔬 Research agent | "Compare 3 solutions and recommend one" | Parallel subagents investigate each, return only conclusions | | 🧩 Headless / server-side | "Run the agent in Node.js" | ui:false + storage:'memory', drive via sdk.send |

> examples/nested-demo is a full low-code example: nested block tree + human confirm + one-click rollback.

Full end-to-end scenarios with copy-paste code (9 cases: low-code builder / form designer / CMS batch / ops console / AI-native / research / server-side / multi-agent / MCP) live in the bundled Agent Skill at skills/page-agent-sdk-integrate/references/use-cases.md (also shipped in the npm package). See [Skills for AI tools](#skills-for-ai-tools-for-integrators) below to install the skill.

When to use / When not

Use it if you want an AI assistant embedded in your web page that edits structured page data (config / component tree / form definitions / CMS content) — safely, rollbackably, via tools — and you don't want to hand-roll an agent harness, schema validation, optimistic lock, or snapshot system.

Don't use it if you only need a stateless chat widget (use any chat UI lib), or you want the AI to drive a browser / automate arbitrary DOM across sites (use Playwright / browser-use), or your data has no schema you can declare.

FAQ

• Q: I want an AI assistant embedded in my web page that can edit the page data. → page-agent-sdk: declare a zod schema + bind, mount the dialog, done. See [30-second quickstart](#30-second-quickstart).
• Q: Alternative to CopilotKit / LangChain for an in-page agent? → page-agent-sdk is framework-agnostic (Vue bundled, host can be React / vanilla), schema-validated, ships optimistic lock + snapshot rollback + MCP, and needs no LangGraph. See [Comparison](#comparison).
• Q: How to let AI safely edit a large JSON on my page? → data + zod schema + write with patch / patches + expectedHash optimistic lock. Invalid edits are rejected pre-write; bad edits rollback in one click.
• Q: Does it work with DeepSeek / OpenAI / any OpenAI-compatible endpoint / Anthropic Claude? → Yes. llm: { apiKey, baseUrl, model } defaults to DeepSeek (OpenAI protocol); llm: { provider: 'anthropic', apiKey, model: 'claude-...' } uses Claude native protocol (dynamic-loaded @langchain/anthropic, optional peer); any LangChain BaseChatModel also accepted.
• Q: Can I run it headless / in Node.js? → Yes. ui:false + storage:'memory', drive via sdk.send. See [headless-demo](#examples).
• Q: Does it support MCP? → Yes. mcp: [{ transport, url }] connects remote MCP servers and injects tools dynamically.

Comparison

| | page-agent-sdk | CopilotKit | LangChain (chat models) | LangGraph | raw LLM tool-calling | |---|---|---|---|---|---| | Framework-agnostic, UI bundled | ✅ Vue bundled, host-agnostic | ❌ React-only | ✅ (no UI) | ✅ (no UI) | ✅ (no UI) | | Schema-validated JSON ops | ✅ zod, whitelist + merge-safe | ⚠️ partial (tool args) | ⚠️ tool args only | ⚠️ tool args only | ❌ | | Incremental patch (jsonPath) | ✅ write patch / edit_data | ❌ | ❌ | ❌ | ❌ | | Optimistic lock + conflict HITL | ✅ expectedHash | ❌ | ❌ | ❌ | ❌ | | Snapshot rollback + checkpoint | ✅ per-path + session | ❌ | ❌ | ❌ | ❌ | | Proactive human-confirm | ✅ built-in | ⚠️ manual | ❌ | ❌ | ❌ | | MCP | ✅ | ✅ | ✅ | ✅ | manual | | Subagents | ✅ | ❌ | ✅ (manual) | ✅ | manual | | Context compression | ✅ 4-layer built-in | ❌ | ❌ | ✅ checkpointer | ❌ | | In-browser persistence | ✅ IndexedDB | ❌ | ❌ | ❌ | ❌ | | Bundle | ~620 KB ESM / 1.4 MB IIFE | React dep | large | large | none |

> Nuance: CopilotKit is a great choice if you're already on React and want a polished AI-chat UI with backend actions; LangChain / LangGraph are general-purpose agent orchestration (server-side strong). page-agent-sdk specifically targets in-page, schema-validated, rollbackable JSON editing — that niche is its differentiation.

30-second quickstart

npm install page-agent-sdk zod @langchain/openai @langchain/core

import { createChatSdk } from 'page-agent-sdk'
import { z } from 'zod'

const page = { title: 'New Products', theme: 'light' }
window.page = page  // optional: mount to window for your page to read; SDK tools operate on `bind` directly

createChatSdk({
  container: '#chat',
  llm: { apiKey: 'sk-...', baseUrl: 'https://api.deepseek.com', model: 'deepseek-v4-flash' },
  systemPrompt: 'You are a page-builder assistant; read/write the main data via tools.',
  data: {
    schema: z.object({
      title: z.string().describe('Page title'),
      theme: z.enum(['light', 'dark']).describe('Theme'),
    }),
    bind: page,
    description: 'Page config',
  },
  approval: { tools: ['write'] }, // confirm writes
  checkpoint: true, // one-click rollback on mistake
}).mount()

User says "title → 'Summer New', theme → dark" → AI calls write with patch (incremental) → schema validation → pre-write confirm → reactive refresh. Said wrong? Click "↩ Undo".

CDN zero-config: ` → ChatSdk.createChatSdk({...})`.

Capabilities

| Capability | Description | Option | |---|---|---| | 🛠 window ops | Read/write registered props, schema validation + incremental patch + snapshot rollback | data | | 🧠 ReAct harness | Pluggable middleware (8 hooks), in-house (no LangGraph) | middleware | | 📋 planning/skills/memory | write_todos / define_skill / AGENTS.md directives | capabilities.* | | 🗄 virtual workspace | In-memory file system; large results offloaded (won't blow context) | capabilities.vfs | | ↩️ rollback | per-path snapshots (small fixes) + session checkpoint (big fixes) | checkpoint | | ✋ human confirm | Pre-write dialog + AI proactive inquiry (uncertain/multi-plan/high-risk) | approval | | ✅ self-verify | Run check before return; on fail, feedback re-injects to self-correct | capabilities.verify | | 🤖 subagents | Delegate subtasks; process stays out of main context | subagent | | 🔌 MCP | Connect remote MCP servers, inject tools dynamically | mcp | | 📦 context compression | 4-layer adaptive compression, presets + LLM summary | contextPreset | | 🧪 complex-task tuned | complex context preset (larger window + later compress + more recall, for multi-step / large-JSON / long-workflow tasks); vfs JSON-aware tools (vfs_json_read / vfs_json_patch) for structured big-JSON ops inside vfs; vfs three-pool LRU (largeresults / drafts / userFiles isolated, no mutual eviction) | contextPreset:'complex', capabilities.vfs | | 🛡️ compression-safe | Live data snapshot + preserved tool results in summary; write returns hint available paths; systemPromptHelpers.reliableWriteRules | built-in | | 💰 Context economy (3.10/3.11+) | Compression cost cap promptSoftCapTokens (defaults to 160K when window ≥320K — huge-window models no longer burn hundreds of thousands of tokens before compressing; reflected via inspect().compression) + agent budget self-awareness (70%-rounds / half-cap token hint, consecutive write-failure reminder, per-invocation roundTokenBudget friendly wrap-up) + tool-description slimming (-40% prompt) | contextOptions.promptSoftCapTokens, roundTokenBudget | | 💾 persistence | IndexedDB multi-session + quota eviction + switch | storage | | 👁 DOM inspect (2.20+) | get_dom structure read + dom_search (selector/text) + dom_info (content/computed styles/event bindings from inline/Vue props/listener recorder) — lazy-injected via the dom-inspect skill so they don't occupy standing tool context | capabilities.domInspect | | 📊 Context inspector | Snapshot actual-LLM-message composition (total / occupancy / category ratio); DebugDrawer 📊 上下文 tab + inspectContext(); zero LLM cost, default on | capabilities.contextInspector | | 🤖 Agent-driven compression (2.33+) | capabilities.agentCompression (opt-in) lets the summary LLM decide per-trigger compression strategy via an inspect_context tool loop (keepRounds / windowRatio / summary mode / recall / preserve); shouldTriggerCompression gate avoids per-message LLM cost; decide failure/timeout degrades to static; decisionTimeoutMs / decisionMaxTokens configurable | capabilities.agentCompression + summaryLlm | | 🎯 Cross-session user preference memory | capabilities.preferences (opt-in, default off — auto-writing the user's browser is behavior-sensitive): the agent captures durable user preferences from conversation — strong signal (explicit commands like "Remember: …", zero LLM) / medium signal (pattern-word prefilter + small-LLM extraction; the core test is durable taste vs this-round task instruction) / behavioral inference not captured (better to miss than to learn wrong — one false preference would ride along every future session); preferences persist independently (preferenceStore, IndexedDB, same shape as storage/skillStorage; same topic later statement overrides earlier, FIFO ≤20); injected as a pin segment into the system prompt each round (survives sessions and compression); manage wrongly-learned entries via sdk.getPreferences()/removePreference(id)/clearPreferences(), plus a read-only DebugDrawer "User preferences" section | capabilities: { preferences: true } + optional preferenceStorage | | ⚡ host actions (2.20+) | Register save/publish/preview etc; SDK auto-generates named tools, agent triggers page ops directly (no trigger_action indirection) | actions | | 🧩 schema tiered disclosure (2.20+) | Large schema → systemPrompt injects top-level overview only (no constraints/no recursion); deep constraints via schema_data on demand; small schema unaffected (full) | schemaHint | | 📌 cross-compress working memory (2.20+) | Pin recent read/query paths + hashes across compression; no re-fetch, correct optimistic-lock hash | capabilities.workingMemory | | 🤖 unattended automation (2.20+) | Resource budget guard (tokenBudget/timeBudgetMs) + fatal-error auto-recovery (maxAutoRetries: restore checkpoint + retry) + cross-refresh resume + sdk.batch(tasks) batch processing | capabilities.automation | | 📐 context resilience (2.30+) | Hard floor contextWindow ≥200K (rejects Done ✓' — rich-text render spots accept inline HTML fragments sanitized via a text allowlist) — switch language and tweak individual strings in one group; DialogMessages (~226 keys) + MESSAGESZHCN/MESSAGESEN_US/resolveDialogMessages exported for custom UIs | dialog.{icons,theme} + i18n.{locale,messages}` |

Capabilities default on (verify/approval/checkpoint default off; proactive humanConfirm default on — AI asks when uncertain/multi-plan instead of guessing). Turn off unneeded ones via capabilities to save tokens.

Design: the schema / systemPrompt / skill three-layer split

The core of letting AI safely edit JSON is a three-layer decoupled split — each layer has its own job, changing one never forces changes to the others:

| Layer | Carrier | Real intent | Loaded when | |---|---|---|---| | Mechanical (structure + validation) | data.schema (zod) | Defines field names/types/shapes; write-time validation guardrail (invalid → structured error, no write); ZodObject top-level keys auto-whitelist (hides undeclared fields, prevents accidental delete/edit) | Fixed at construction; field .describe() text auto-extracted into systemPrompt | | Generic rules (identity + write methodology) | systemPrompt | Agent identity; reliableWriteRules (read before write, fields per describe, retry on validation error, prefer incremental patch) | Every round (persistent) | | Deep business (semantics + edit recipes) | skills (defineSkill) | Component-library specs, detailed field business semantics, scenario-specific edit strategies, glossaries | On-demand (agent sees name+description index, calls load_skill to pull fu

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: whyymj
• Source: whyymj/page-agent-sdk
• License: ISC

Install and usage instructions live in the source repository linked above.