Loading…

Agent Surface

experimental

A region an agent can operate through tools — yours or a browser agent's via WebMCP — and a person can take back at any moment.

AI
5 files
No extra npm packages
Accessibility notes

Playground

Installation

One command and the file is in your project, or copy it in by hand.

$pnpm dlx @dowel-ui/cli add agent-surface

No npm packages are needed beyond what Dowel already requires.

Usage

Imported from your own path — the file is yours, so this is an import like any other.

app/page.tsxTSX

import { AgentSurface } from "@/components/ui/agent-surface";

Examples

Every example the tests run, live and operable, side by side.

Default
Held By The Agent
Agent Needs You
Browser Agents

API

Generated from the component's own types, so a prop cannot appear here without existing.

<AgentSurface>

Prop	Type	Default
`agentName` How the agent is referred to in announcements and the baton.	`string`	`"Agent"`
`announceCalls` Also announce each finished call. Off: six announcements a second is noise.	`boolean`	`false`
`apiRef`	`Ref<AgentSurfaceApi>`	—
`defaultHolder`	`ControlHolder`	`"shared"`
`exposedTo` With `webmcp`: origins, beyond the page's own, that may see the tools within the page's frames. A tool's own `exposedTo` replaces this.	`readonly string[]`	—
`holder`	`ControlHolder`	—
`labels`	`Partial<AgentSurfaceLabels>`	—
`name` Prefixes every tool name, so two surfaces on one page cannot collide.	`string`	—
`onApprovalRequest` Asked before any call that needs approval. Takes precedence over an `agent-approvals` mounted inside. With neither, those calls are refused.	`ApprovalHandler`	—
`onControlChange`	`(change: ControlChange) => void`	—
`onToolCall` Every call, each time its state changes.	`(call: AgentToolCall) => void`	—
`takeOverOn` `input`: while the agent drives, the person operating a control here takes over — they are already acting, and making them find a button first is the agent racing them. Anything inside `[data-agent-ui]` is exempt: mark your own approval or chat UI with it. `explicit`: only the baton takes over.	`"input" \| "explicit"`	`"input"`
`webmcp` Expose the tools to browser agents through WebMCP, where supported.	`boolean`	`false`
`children`	`ReactNode`	—

Plus every attribute of <div>.

Accessibility

Every change of control is announced through a polite status region that exists from first paint — "Agent has control", "You have control. Agent is paused", "Agent needs you: sign in to continue" — and the surface's ring is never the only signal of who holds it. Finished tool calls are announced only with announceCalls, because an agent making several calls a second would otherwise talk over everything. While the agent drives, a person operating any control inside the surface takes over (takeOverOn="input"), so a keyboard or switch user never has to race the agent to a button first; tabbing and reading do not count, only activating or editing something, and nothing inside [data-agent-ui] — the baton, an approval, the composer — counts at all. An element a tool acts on is outlined while it is used, so the person can see what the agent touched, and focus is never moved by a tool call. While the person holds control every call is refused, reads included, because taking over is often done to type something the agent should not see.

Quality

Measured from the source and its tests at build time.

All scores

8/8

checks passed

Tested — passes
axe assertion — passes
Keyboard tested — does not apply
Storybook examples — passes
Accessibility documented — passes
Semantic tokens only — passes
Motion from tokens — passes
className merged — passes
Visible focus — does not apply
No fixed widths — passes

Deal

Stage

Amount

Acme expansion

Negotiation

$48,000

Bolt renewal

Renewal

$120,000

Cove pilot

Discovery

$12,000

Dune upsell

Proposal

$30,000

Echo renewal

Renewal

$64,000

Prop

Type

Default

agentName

How the agent is referred to in announcements and the baton.

string

"Agent"

announceCalls

Also announce each finished call. Off: six announcements a second is noise.

boolean

false

apiRef

Ref<AgentSurfaceApi>

—

defaultHolder

ControlHolder

"shared"

exposedTo

With webmcp: origins, beyond the page's own, that may see the tools within the page's frames. A tool's own exposedTo replaces this.

readonly string[]

—

holder

ControlHolder

—

labels

Partial<AgentSurfaceLabels>

—

name

Prefixes every tool name, so two surfaces on one page cannot collide.

string

—

onApprovalRequest

Asked before any call that needs approval. Takes precedence over an agent-approvals mounted inside. With neither, those calls are refused.

ApprovalHandler

—

onControlChange

(change: ControlChange) => void

—

onToolCall

Every call, each time its state changes.

(call: AgentToolCall) => void

—

takeOverOn

input: while the agent drives, the person operating a control here takes over — they are already acting, and making them find a button first is the agent racing them. Anything inside [data-agent-ui] is exempt: mark your own approval or chat UI with it. explicit: only the baton takes over.

"input" | "explicit"

"input"

webmcp

Expose the tools to browser agents through WebMCP, where supported.

boolean

false

children

ReactNode

—

Agent Surface

Installation

Usage

Examples

API

<AgentSurface>

Accessibility

Quality

Agent Surface

Agent transcript

Installation

Usage

Examples

API

<AgentSurface>

Accessibility

Quality

Agent transcript