Adapter types

The contract between the chat widget and the agent that drives it.

The contract between the chat widget and the agent that drives it. An adapter owns the model and tool loop and reports what happens as a stream of parts; the widget only renders them. Read this page to write your own adapter, or to understand what createCloudAdapter and createLocalAdapter hand the chat.

Import

import type {
  AdapterStatus,
  AgentAdapter,
  AgentMessage,
  AgentPart,
  AgentRunRequest,
  AgentStreamPart,
  ModelChoice,
  ToolCallState,
  ToolDescriptor,
  ToolOutput,
} from "@webmcp-agents/chat";

Example

A minimal adapter with no model: it calls the page’s first tool through req.callTool, then reports what it found. It shows the shape every adapter follows: message-start, the parts, then finish.

import type { AgentAdapter } from "@webmcp-agents/chat";

// A minimal adapter: no model. It calls the page's first tool, then
// says what happened. Pass it to <AgentChat adapter={echo} />.
export const echo: AgentAdapter = {
  id: "echo",
  label: "Echo",
  status: () => ({ state: "ready" }),

  async *run(req) {
    const messageId = crypto.randomUUID();
    yield { type: "message-start", messageId };

    // Read tools fresh: they change as the page changes.
    const tool = req.tools[0];
    if (tool) {
      const id = crypto.randomUUID();
      const call = { id, name: tool.name, input: {} };
      yield { type: "tool-call", messageId, ...call };

      // One tool at a time (one page, one cursor). Never rejects.
      const output = await req.callTool(call);
      const text = output.content[0]?.text ?? "";
      yield output.isError
        ? { type: "tool-error", id, error: text }
        : { type: "tool-result", id, output };
    }

    const delta = `This page has ${req.tools.length} tools.`;
    yield { type: "text-delta", messageId, delta };
    yield { type: "finish", reason: "stop" };
  },
};

Options

Each type’s members, one table per type. The ones you implement are AgentAdapter (and its run); the others are what you receive or yield.

AgentAdapter

An agent the chat can talk to: the model and tool loop behind a stream of parts.

A ModelChoice describes one model in the picker:

AdapterStatus

Whether an adapter can run right now. The composer explains any state but ready.

AgentRunRequest

What an adapter gets for one run: one user message, possibly many model steps.

AgentStreamPart

What an adapter reports while it runs, in order. Start each assistant message with message-start; text, reasoning and tool calls refer to it by messageId. End the run with finish or error.

AgentMessage and AgentPart

One turn of the conversation: { id: string; role: "user" | "assistant"; parts: AgentPart[] }. A part is one of:

ToolCallState

"running" | "awaiting-confirmation" | "done" | "error" | "cancelled": where a tool call is. awaiting-confirmation means it is parked on a control the person must click.

ToolDescriptor and ToolOutput

A ToolDescriptor is a page tool as the model sees it:

A ToolOutput is a tool call’s result: an MCP result, { content, isError?, structuredContent? } (ModelContextToolResult from @webmcp-agents/core).

Returns

An adapter’s run returns an AsyncIterable<AgentStreamPart>: the parts above, in order, ending with finish or error.

Notes

• Run tool calls one at a time: one page, one cursor. The session matches confirmation events to calls by tool name.
• Yield tool-result or tool-error for every tool-call, with the same id.
• Create an adapter once, at module scope, not during render: the session and the status hook key on the adapter object.
• An adapter without status() is always ready. With subscribe(), the widget re-reads status() whenever you call the listener.

See also

• Add the chat
• createCloudAdapter and createLocalAdapter
• sessionReducer
• callModelContextTool