--- title: "Agentic UI" description: "Interface patterns for chat, copilots, generative UI, tool progress, approvals, and resumable agent work." url: "https://agentsurface.dev/docs/agentic-ui" lastVerified: 2026-09-24 lastModified: 2026-09-25T09:56:33.000Z --- ## Summary [#summary] Agentic UI is the product surface around agent work. A good agentic interface shows what the agent is doing, what it needs from the user, what it changed, and how the user can stop, correct, approve, or resume the work. * Use chat for conversation and back it with explicit controls. * Render tool calls and workflow state as first-class UI events. * Separate draft, approval, execution, and completion states. * Make cancellation and correction available while work is running. * Preserve enough history for trust, audit, and recovery without dumping raw traces into the UI. * Keep agent logic and model API keys server-side; the client only ever sees the events the server chooses to stream. ## Section Pages [#section-pages] This page is the overview: the UI shapes, the event model, tool rendering, and streaming. Three topics have their own pages: * [Session Control](/docs/agentic-ui/session-control) - the controller layer between the UI and the agent loop: modes, subagent surfacing, tool approvals, thread state, and mid-run steering. * [MCP Apps](/docs/agentic-ui/mcp-apps) - interactive UI delivered through MCP tool results, so a server can ship a rich interface to any supporting client. * [Browser Agent Accessibility](/docs/agentic-ui/browser-agent-accessibility) - landmarks, native controls, computed names, form labels, and untrusted instructions in accessibility content. ## UI Shapes [#ui-shapes] | Shape | Use when | Avoid when | | ----------------------- | ------------------------------------------------------------ | --------------------------------------------------- | | Chat | The task is conversational or exploratory | The main job is repeated form-like execution | | Copilot panel | The agent assists inside an existing workflow | The agent needs full-screen focus or complex review | | Command palette | The user knows the action but wants natural-language routing | The action needs long explanation or approval | | Generative UI | Output needs custom controls, forms, previews, or charts | Plain text is enough | | Workflow status page | Work is long-running, resumable, or multi-step | The response completes inside one request | | Review queue | Human approval is part of the product | The action is low-risk and reversible | | Background notification | The agent acts asynchronously or proactively | The user expects immediate conversational feedback | ## Event Model [#event-model] Agentic UI should consume structured events rather than scraped prose. Common event types: * `message.created` * `agent.started` * `agent.thinking` * `tool.started` * `tool.progress` * `tool.completed` * `tool.failed` * `workflow.step.started` * `workflow.step.completed` * `approval.requested` * `approval.resolved` * `artifact.created` * `agent.completed` * `agent.failed` Every event should carry a stable run ID, timestamp, source, and display-safe summary. Sensitive tool inputs and raw model prompts should stay out of client-visible events unless the product explicitly exposes them. You do not have to invent this event vocabulary from scratch. AG-UI, originated at CopilotKit, is the current de facto layer for streaming agent state to a UI across vendors - adopted via SDKs in Microsoft Agent Framework, Google ADK, AWS Strands, Mastra, and others, but with no canonical pinned spec version; adopt it through a maintained SDK rather than hand-implementing the wire format. Track its status on the [Emerging Standards Watchlist](/docs/protocols/emerging-standards). ## Tool Rendering [#tool-rendering] Do not render all tool calls as generic JSON. The UI should translate tool state into useful product affordances: * search tools: query, source count, and selected sources * write tools: draft preview, diff, and approval controls * purchase or send tools: recipient, amount, destination, and confirmation state * browser tools: current URL, screenshot, and extracted result * code tools: command, exit code, artifact links, and truncated logs * retrieval tools: cited documents and confidence signals For risky tools, split "prepare" from "commit." The agent can draft an email, create an invoice preview, or stage a file change, but the UI should require explicit approval before sending, charging, deleting, or publishing. ## Approval and Steering [#approval-and-steering] Risky actions need an explicit approval state machine, and a running agent needs affordances to be corrected without starting over. Both belong to the controller layer, and both are covered in full on [Session Control](/docs/agentic-ui/session-control): the durable approval states an action moves through, and the steering controls that let a user edit the goal, swap a tool, revise a draft, or inject a new instruction mid-run. ## Context Display [#context-display] Show enough context for trust: * active goal * selected resources * connected account or workspace * important constraints * tool progress * sources used * pending approvals * final changes Do not expose internal chain-of-thought, full prompts, credentials, hidden policy text, or raw traces. Summaries and structured event logs are safer product surfaces. ## Streaming [#streaming] Streaming can carry more than tokens. A mature interface streams: * assistant text * tool progress * workflow steps * citations as they are selected * partial artifacts * warnings and recoverable errors * approval requests Token streaming should not block structured state updates. If the final answer is still generating, the UI should still be able to show that a tool failed, a source was selected, or approval is needed. ## Failure Modes [#failure-modes] * **Mystery work:** The UI says "thinking" while the agent calls tools or changes state. Show specific, safe progress. * **Invisible side effects:** The agent mutates data without a preview or durable audit trail. Stage and approve risky actions. * **Chat-only control:** The user must type corrections that should be buttons, forms, or diff controls. * **Lost approvals:** A refresh or reconnect loses the approval request. Store approval state server-side. * **Trace leakage:** The UI exposes internal prompts, credentials, or private tool payloads. Use display-safe event summaries. * **No recovery path:** A tool fails and the only option is to restart. Offer retry, revise, skip, or escalate. ## Checklist [#checklist] Before shipping an agentic UI, verify: * every run has a visible status * every risky action has a preview and approval boundary * tool calls have product-specific renderers where useful * cancellation works during long-running work * reconnecting restores state * errors are actionable * sources and artifacts are accessible after completion * logs and traces exist outside the UI for debugging * the UI distinguishes draft output from executed side effects ## Related [#related] * [Session Control](/docs/agentic-ui/session-control) * [MCP Apps](/docs/agentic-ui/mcp-apps) * [Browser Agent Accessibility](/docs/agentic-ui/browser-agent-accessibility) * [Human Approval](/docs/tool-design/human-approval) * [Tool Design](/docs/tool-design) * [Durable Execution](/docs/agents/durable-execution)