AgentChat

A chat launcher and a non-modal chat panel whose agent works the live page through its tools while the person watches.

A chat launcher and a non-modal chat panel whose agent works the live page through its tools while the person watches. Use it to give a page an assistant in one line; by default the panel docks beside the page instead of covering it.

Import

import { AgentChat } from "@webmcp-agents/chat";
import type { AgentChatProps } from "@webmcp-agents/chat";
import "@webmcp-agents/chat/chat.css";

Example

import { AgentChat } from "@webmcp-agents/chat";
import { WebAgentsProvider } from "@webmcp-agents/react";
import type { ReactNode } from "react";

import { shopper } from "@/agents";
import { tools } from "@/tools";

// Inside the provider, so the assistant sees the tools this page
// has on. Import chat.css once in your entry file.
export function Page({ children }: { children: ReactNode }) {
  return (
    <WebAgentsProvider tools={tools}>
      {children}
      <AgentChat
        agent={shopper}
        title="Shop assistant"
        position="bottom-left"
        layout="floating"
        suggestions={["What is in my cart?"]}
      />
    </WebAgentsProvider>
  );
}

With a cloud and an on-device adapter, the person picks in a switcher. Create the adapters once, at module scope:

import { createCloudAdapter } from "@webmcp-agents/chat";
import { createLocalAdapter } from "@webmcp-agents/local-agent";

const adapters = [
  createCloudAdapter(),
  createLocalAdapter({ instructions: "Help with the store." }),
];
// <AgentChat adapters={adapters} agent={shopper} />

Props

Returns

A portal into a host <div> appended to document.body (class wa-chat, data-position, data-layout and the data-web-agents-ui attribute). It renders null until the host exists.

Layout

• Docked (default): the open panel sits on the position side, full height, and the page gets a body margin so the agent never works under the chat. Drag the inner edge, or focus it and use the arrow keys (Shift for bigger steps, Home and End for min and max), to resize. The width runs from 320 px up to the window minus 360 px (at most 720 px), starts at 380 px, and is remembered in localStorage.
• While docked, <html> gets data-wa-chat-dock="left|right" and --wa-chat-inset-left / --wa-chat-inset-right. Offset your own fixed UI (drawers, toasts) with them.
• Floating: the pop-over stays in the corner, over the page.
• Below 640 px the panel is a bottom sheet in either layout.

Theming

Import @webmcp-agents/chat/chat.css once. Every rule is scoped by a .wa-chat* class and sits outside any cascade layer. Override the custom properties on .wa-chat (or on your className):

Dark mode follows prefers-color-scheme (unless an ancestor or the host has data-theme="light"), or data-theme="dark" on an ancestor or the host.

Notes

• Render it inside <WebAgentsProvider> so the agent sees the tools the page has on.
• Create custom adapters once, at module scope, not during render: the session and the status hook key on the adapter object.
• The host carries data-web-agents-ui, so typing in the chat never makes the agent cursor yield.
• The conversation survives route changes and reloads (sessionStorage, last 60 messages). A reload marks any running tool call as cancelled.
• The chosen adapter is remembered in localStorage (web-agents:chat:adapter) while it is still offered. The switcher is disabled while a run streams.
• An adapter with prepare() and a needs-download, downloading or error status shows a download card with the size, Cancel, and a button to switch to another adapter.
• “Try again” after a failed run resumes the turn (see resumable). It is hidden for chat_disabled.
• Escape closes the panel and returns focus to the launcher.

See also

• Add the chat, the page that teaches it
• defineWebAgent, the agent prop
• createCloudAdapter and createChatHandler, the two ends of /api/chat
• useAgentSession, to build your own chat UI
• useWebAgent, to run an agent with no chat on the page
• Adapter types
• createLocalAdapter