API reference

Reference for every public API of the @webmcp-agents/* packages, one page per API.

Reference for every public API of the @webmcp-agents/* packages, one page per API. Every page has the same shape: an import line, a complete example, one table row per option (type, default, what it is for), what it returns, the edge cases, and where to read more. Each package folder starts with a README that lists its APIs.

New here? Reference is for looking things up. To learn the library, install it in your framework and follow the Build path from Define a tool; How it works explains the ideas behind it.

The packages make an agent’s work on a WebMCP page (document.modelContext) visible to the person using it: a ghost cursor, fields typed in place, a parked “confirm” state. A tool is execute plus an optional target: nothing is added to your markup for the cursor, which finds controls by role and accessible name.

Packages

Package	What it’s for	Docs
`@webmcp-agents/core`	The visual layer (agent cursor), typed tools (`defineWebTool`), `createWebAgents`, the locator, the tool registry, `executeTool`, tool error codes, WebMCP types, and the polyfill it loads where the browser has no WebMCP	core
`@webmcp-agents/react`	`<WebAgentsProvider>` and `useWebTool` to put a catalog and component tools on the page from React	react
`@webmcp-agents/tools`	Common tools, ready-made: `get_time`, `get_location`, `get_page`, `go_to`, `go_back`, `scroll_to`, `set_theme`	tools
`@webmcp-agents/polyfill`	Deprecated: the polyfill is `@webmcp-agents/core/polyfill` now, loaded by the provider itself; this package re-exports it	polyfill
`@webmcp-agents/devtools`	A panel to see each tool’s control, fields and `match`, run and cancel tools, and a timeline of agent calls	devtools
`@webmcp-agents/chat`	A chat widget, `defineWebAgent` (instructions, tool subsets, sub-agents; `agent.invoke`), `useWebAgent`, the agent adapter contract, a server handler for any frontier model (AI SDK) and a Vite dev plugin	chat
`@webmcp-agents/local-agent`	An on-device agent (Chrome’s Prompt API or transformers.js) behind the same adapter contract	local-agent
`@webmcp-agents/vercel-api`	The chat handler as a Vercel Function, with origin check, rate limits and a daily budget	vercel-api

Where to start

New to the library: Installation, then the Build path: Define a tool, Define an agent, Add the chat.
Make a page agent-ready: write a tool in a component with useWebTool, put the app-wide ones in a catalog with defineWebTool and hand it to <WebAgentsProvider tools={tools}> (or createWebAgents without React). Add common tools beside yours.
Call a tool or an agent from your own UI: tool.invoke(…) (defineWebTool), agent.invoke(…) (defineWebAgent), or useWebAgent for live status.
Show what the agent does: installAgentVisuals (the provider installs it for you) and cursor.css. Control which element the cursor goes to with a target and locate.
Add the chat: <AgentChat agent={…} /> (it talks to your /api/chat by default; add createLocalAdapter for an on-device model).
When a tool fails: every failure carries a code (Error [timeout]: …), see tool error codes.
Debug tools: the devtools panel (Alt+Shift+A), which <WebAgentsProvider> installs in development: each tool’s control, fields and match. Without the provider: installWebAgentsDevtools.
Deploy the examples: Deploy.