---
slug: reference
description: "Reference for every public API of the @webmcp-agents/* packages, one page per API."
---

# API reference

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](</docs/installation>)
and follow the Build path from [Define a tool](/docs/build/define-a-tool); [How it works](/docs/concepts/how-it-works)
explains the ideas behind it.

The packages make an agent's work on a [WebMCP](https://developer.chrome.com/docs/ai/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](/docs/reference/core) |
| `@webmcp-agents/react` | `<WebAgentsProvider>` and `useWebTool` to put a catalog and component tools on the page from React | [react](/docs/reference/react) |
| `@webmcp-agents/tools` | Common tools, ready-made: `get_time`, `get_location`, `get_page`, `go_to`, `go_back`, `scroll_to`, `set_theme` | [tools](/docs/reference/tools) |
| `@webmcp-agents/polyfill` | Deprecated: the polyfill is `@webmcp-agents/core/polyfill` now, loaded by the provider itself; this package re-exports it | [polyfill](/docs/reference/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](/docs/reference/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](/docs/reference/chat) |
| `@webmcp-agents/local-agent` | An on-device agent (Chrome's Prompt API or transformers.js) behind the same adapter contract | [local-agent](/docs/reference/local-agent) |
| `@webmcp-agents/vercel-api` | The chat handler as a Vercel Function, with origin check, rate limits and a daily budget | [vercel-api](/docs/reference/vercel-api) |

## Where to start

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