Tool Call Rendering
Render your agent's tool calls with custom UI components.
Open your coding agent in your project's folder, or in an empty folder for a new app.This runs in a coding agent on your computer.
/** * Agent factories for the Strands TypeScript showcase backend. * * `buildShowcaseAgent` is the single shared agent that serves the vast * majority of demos (the frontend differentiates each demo via * useFrontendTool / useRenderTool / useHumanInTheLoop / useAgentContext). * It mirrors the Python sibling's `build_showcase_agent` minus A2UI. * * The tool-free specialized agents (voice, byoc-hashbrown, byoc-json-render) * are mounted on dedicated sub-paths by `server.ts`. */import { readFileSync } from "node:fs";import { dirname, join } from "node:path";import { fileURLToPath } from "node:url";import { Agent, tool } from "@strands-agents/sdk";import { z } from "zod";import type { RunAgentInput } from "@ag-ui/core";import { StrandsAgent } from "@ag-ui/aws-strands";import type { StrandsAgentConfig } from "@ag-ui/aws-strands";import { A2UI_OPERATIONS_KEY, createSurface, updateComponents, updateDataModel,} from "@ag-ui/a2ui-toolkit";import { createModel } from "./model-factory";import { SHOWCASE_TOOLS } from "./tools";import { BoardStateStrandsAgent } from "./todo-state-sync";import { withStateContext, salesStateFromArgs, salesStateFromResult, notesStateFromArgs, stepsStateFromArgs, documentStateFromArgs, makeSubagentStateFromResult,} from "./state";import { SYSTEM_PROMPT, VOICE_SYSTEM_PROMPT, BYOC_HASHBROWN_SYSTEM_PROMPT, BYOC_JSON_RENDER_SYSTEM_PROMPT,} from "./prompts";export class ShowcaseStrandsAgent extends BoardStateStrandsAgent { override async *run(inputData: RunAgentInput) { // The adapter exposes context during model calls and restores history afterward. yield* super.run(withStateContext(inputData)); }}export async function buildShowcaseAgent( openaiApi: "chat" | "responses" = "chat",): Promise<StrandsAgent> { const config: StrandsAgentConfig = { toolBehaviors: { // The tool keeps the sales pipeline in appState; this snapshot, built // from the args, only carries it to the UI. Keep the call/result in // message snapshots too so completed threads can replay them. manage_sales_todos: { stateFromArgs: salesStateFromArgs, }, get_sales_todos: { stateFromResult: salesStateFromResult }, // Shared State (Read + Write) — notes panel. set_notes: { stateFromArgs: notesStateFromArgs }, // gen-ui-agent — live progress card driven by set_steps transitions. set_steps: { stateFromArgs: stepsStateFromArgs }, // shared-state-streaming — stream the document string into state. write_document: { stateFromArgs: documentStateFromArgs }, // Sub-agents — append a delegation entry carrying the actual output. research_agent: { stateFromResult: makeSubagentStateFromResult("research_agent"), }, writing_agent: { stateFromResult: makeSubagentStateFromResult("writing_agent"), }, critique_agent: { stateFromResult: makeSubagentStateFromResult("critique_agent"), }, }, }; const strandsAgent = new Agent({ model: await createModel({ openaiApi }), systemPrompt: SYSTEM_PROMPT, tools: SHOWCASE_TOOLS, }); return new ShowcaseStrandsAgent({ agent: strandsAgent, name: "strands_agent", description: "A polished CopilotKit demo assistant: chat, tools, shared state, HITL, sub-agents.", config, });}/** * Published Strands Chat Completions drops parallel call indices before native * aggregation. Responses preserves each call and emits complete, ordered blocks. * Rich chat intentionally buffers tool arguments; the shared agent keeps Chat * for demos that demonstrate progressive state and UI updates. */export function buildRichChatAgent(): Promise<StrandsAgent> { return buildShowcaseAgent("responses");}/** Tool-free agent for the voice demo (transcription + basic chat). */export async function buildVoiceAgent(): Promise<StrandsAgent> { const strandsAgent = new Agent({ model: await createModel(), systemPrompt: VOICE_SYSTEM_PROMPT, tools: [], }); return new StrandsAgent({ agent: strandsAgent, name: "voice_agent", description: "Simple assistant for the voice demo — no tools.", });}/** Tool-free hashbrown UI-kit envelope generator (declarative-hashbrown). */export async function buildByocHashbrownAgent(): Promise<StrandsAgent> { const strandsAgent = new Agent({ model: await createModel(), systemPrompt: BYOC_HASHBROWN_SYSTEM_PROMPT, tools: [], }); return new StrandsAgent({ agent: strandsAgent, name: "byoc_hashbrown", description: "Hashbrown UI-kit envelope generator for the declarative-hashbrown demo.", });}/** Tool-free json-render flat-spec generator (declarative-json-render). */export async function buildByocJsonRenderAgent(): Promise<StrandsAgent> { const strandsAgent = new Agent({ model: await createModel(), systemPrompt: BYOC_JSON_RENDER_SYSTEM_PROMPT, tools: [], }); return new StrandsAgent({ agent: strandsAgent, name: "byoc_json_render", description: "json-render flat-spec generator for the declarative-json-render demo.", });}// ---------------------------------------------------------------------------// A2UI Fixed Schema (declarative-generative-ui) — dedicated backend tool.// ---------------------------------------------------------------------------//// Unlike the dynamic A2UI demo (which relies on the adapter auto-injecting a// `generate_a2ui` tool to *generate* a surface), the fixed-schema demo wires a// single plain backend tool — `display_flight` — that returns the// `a2ui_operations` envelope (createSurface -> updateComponents ->// updateDataModel). The component tree is fixed and authored ahead of time// (./a2ui_schemas/flight_schema.json); only the *data* changes per call. The// runtime A2UIMiddleware detects the envelope in the tool result and paints.// No sub-agent, no generation, no `generate_a2ui` injection.//// The schema's component names + data paths must match the showcase frontend// catalog at src/app/demos/a2ui-fixed-schema/a2ui/{definitions,renderers,// catalog}.ts — catalog id `copilotkit://flight-fixed-catalog`. This mirrors// the canonical langgraph-python demo (src/agents/a2ui_fixed.py).const _A2UI_DIR = dirname(fileURLToPath(import.meta.url));const A2UI_FIXED_CATALOG_ID = "copilotkit://flight-fixed-catalog";const A2UI_FIXED_SURFACE_ID = "flight-fixed-schema";// Fixed, pre-authored component layout. Loaded from JSON so it can be authored// and reviewed independently of the agent code.const FLIGHT_SCHEMA: Array<Record<string, unknown>> = JSON.parse( readFileSync(join(_A2UI_DIR, "a2ui_schemas", "flight_schema.json"), "utf-8"),);const A2UI_FIXED_SYSTEM_PROMPT = "You help users find flights. When asked about a flight, call " + "`display_flight` exactly ONCE with origin, destination, airline, and " + 'price. Use short airport codes (e.g. "SFO", "JFK") for ' + 'origin/destination and a price string like "$289". The tool\'s return ' + "value is an A2UI surface descriptor — the flight card is already rendered " + "to the user; do NOT call `display_flight` again for the same trip and do " + "NOT repeat the flight details in text. After the tool returns, reply with " + "one short confirmation sentence and stop.";/** * Dedicated agent for the A2UI fixed-schema demo. Returns the envelope as a * plain OBJECT (not a JSON string): the Strands TS SDK wraps an object * tool-return in a `json` content block the adapter reads and re-stringifies * into the TOOL_CALL_RESULT the client A2UIMiddleware scans for * `a2ui_operations`. (A bare string return lands in no content block and the * result comes through empty — unlike the Python SDK, which wraps strings.) */export async function buildA2uiFixedSchemaAgent(): Promise<StrandsAgent> { const displayFlight = tool({ name: "display_flight", description: "Show a flight card for the given trip. Use short airport codes " + '(e.g. "SFO", "JFK") for origin/destination and a price string like ' + '"$289". After this tool returns, the flight card is already rendered ' + "to the user via the A2UI surface — do NOT call it again for the same " + "flight; reply with one short confirmation sentence and stop.", inputSchema: z.object({ origin: z.string().describe('Origin airport code, e.g. "SFO".'), destination: z.string().describe('Destination airport code, e.g. "JFK".'), airline: z.string().describe('Airline name, e.g. "United".'), price: z.string().describe('Price string, e.g. "$289".'), }), callback: ({ origin, destination, airline, price }) => ({ [A2UI_OPERATIONS_KEY]: [ createSurface(A2UI_FIXED_SURFACE_ID, A2UI_FIXED_CATALOG_ID), updateComponents(A2UI_FIXED_SURFACE_ID, FLIGHT_SCHEMA), updateDataModel(A2UI_FIXED_SURFACE_ID, { origin, destination, airline, price, }), ], }), }); const strandsAgent = new Agent({ // Chat Completions API: the Responses adapter buffers tool-call argument // deltas, which would defeat A2UI's progressive surface streaming. model: await createModel({ openaiApi: "chat" }), systemPrompt: A2UI_FIXED_SYSTEM_PROMPT, tools: [displayFlight], }); return new StrandsAgent({ agent: strandsAgent, name: "a2ui_fixed_schema", description: "A2UI surface from a fixed, pre-authored schema (direct backend tool)", });}// ---------------------------------------------------------------------------// A2UI Dynamic Schema (declarative-gen-ui) — adapter auto-injects generate_a2ui.// ---------------------------------------------------------------------------//// Unlike the fixed-schema demo (which wires a `display_flight` tool returning a// pre-authored envelope), the dynamic demo lets the agent *generate* the// surface layout on the fly. The Next.js route// (app/api/copilotkit-declarative-gen-ui/route.ts) sets// `a2ui: { injectA2UITool: true, defaultCatalogId: "declarative-gen-ui-catalog" }`;// the runtime forwards the flag, the Strands adapter auto-injects a// `generate_a2ui` tool and drives a secondary render planner. The// `config.a2ui` block below supplies the catalog id stamped into generated// surfaces and the composition guide that teaches the planner the page's// catalog. Mirrors the ag-ui dynamic-schema reference example.//// The compositionGuide MUST describe the catalog the page registers at// src/app/demos/declarative-gen-ui/a2ui/{definitions,renderers,catalog}.ts// (catalog id `declarative-gen-ui-catalog`): Card / StatusBadge / Metric /// InfoRow / PrimaryButton / PieChart / BarChart / DataTable, composed inside// the basic catalog's Row / Column / Text (`includeBasicCatalog: true`).//// Grounding dataset + composition rules are kept in spirit with the frontend// `sales-context.ts` (SALES_DATASET + COMPOSITION_RULES) the page registers via// `useAgentContext`. The frontend context steers the PRIMARY agent; this// compositionGuide is the channel the adapter feeds to the secondary// `render_a2ui` planner (it gets `guidelines`, not the frontend App Context),// so the planner is self-contained.const A2UI_DYNAMIC_CATALOG_ID = "declarative-gen-ui-catalog";const A2UI_DYNAMIC_SALES_DATASET = `Vantage Threads (fictional B2B apparel company) — Q2 sales data. Ground every visual in these numbers; invent only plausible details consistent with them.- Quarterly revenue: $4.2M (up 12% QoQ). New customers: 186 (up 8%). Win rate: 31% (down 2pts). Avg deal size: $22.6k (up 5%).- Revenue by region: North America $1.9M, EMEA $1.3M, APAC $720k, LATAM $280k.- Monthly revenue: Jan $1.21M, Feb $1.34M, Mar $1.65M, Apr $1.38M, May $1.42M, Jun $1.40M.- Reps (vs quota): Dana Whitfield 124%, Marcus Lee 108%, Priya Sharma 97%, Tom Okafor 88%, Elena Vasquez 71%.- At-risk: total $615k ARR across 3 accounts — Northwind Retail ($340k renewal, no contact 6 weeks; severity high), Cascadia Outfitters ($180k, champion left; severity medium), Atlas Goods ($95k, stalled legal review; severity medium).- Biggest account: Meridian Apparel Group — owner Dana Whitfield, region North America, ARR $612k, renewal Sep 30, last contact 3 days ago, health green, 4 open opportunities worth $210k.- Meridian revenue by product line: Outerwear $260k, Footwear $180k, Accessories $112k, Custom $60k.`;const A2UI_DYNAMIC_COMPOSITION_RULES = `Use ONLY these exact component names (the registered catalog — any other name fails to render): Card, Column, Row, Text, Metric, PieChart, BarChart, DataTable, StatusBadge, InfoRow, PrimaryButton. The single-value KPI tile component is named exactly "Metric" (NOT "MetricTile" or "MetricCard").Pick A2UI components by the shape of the question — never ask which chart the user wants:1. Overall snapshot / "sales dashboard" → a Column (gap 16) whose first child is a Row (gap 16) of 4 Metric components (each with trend + trendValue), followed by a Row with a PieChart (revenue by region) next to a BarChart (monthly revenue, all six months Jan-Jun). Do NOT wrap the dashboard in a surrounding Card — the charts carry their own card chrome. Do NOT use StatusBadge, DataTable, or InfoRow here.2. Rep / team performance → a Column (gap 16) with a Card containing a DataTable (columns: rep, attainment, pipeline) next to or above a BarChart of quota attainment % per rep — no StatusBadge or InfoRow.3. Risk / health checks → a Column (gap 16): first a Row (gap 16) of 3 Metric components (ARR at risk $615k trend down, accounts at risk 3, biggest exposure Northwind $340k), then a Row (gap 16) with one compact Card per at-risk account (title = account name, subtitle = ARR at stake) containing a StatusBadge (error for high severity, warning otherwise) above a one-line Text with the reason and the recommended next action — no DataTable or InfoRow.4. Single account/entity details → a Row (gap 16) with a Card of InfoRow facts (owner, region, ARR, renewal date, last contact) next to a PieChart of that account's revenue by product line — no DataTable or StatusBadge.5. Part-of-whole follow-ups → PieChart; trends or comparisons over time/categories → BarChart.Compose generously — a dashboard should feel like a real analytics product, not a single widget.`;const A2UI_DYNAMIC_COMPOSITION_GUIDE = `${A2UI_DYNAMIC_SALES_DATASET}\n\n${A2UI_DYNAMIC_COMPOSITION_RULES}`;// Mirrors the langgraph-python demo's a2ui_dynamic.py SYSTEM_PROMPT.const A2UI_DYNAMIC_SYSTEM_PROMPT = "You are the embedded sales analyst for Vantage Threads, the fictional " + "B2B apparel company described in your App Context. Answer every " + "business question by calling `generate_a2ui` to draw a rich visual " + "surface, and keep the chat reply to one short sentence.\n\n" + "Ground every number in the sales dataset from App Context — never " + "invent figures that contradict it. Follow the dashboard composition " + "rules from App Context when choosing components: pick the component " + "by the shape of the question (snapshot → composed KPI dashboard with " + "charts; team performance → table; risk → status badges; single " + "account → info rows; part-of-whole → pie; trend/comparison → bar). " + "Never ask the user which chart they want. `generate_a2ui` takes no " + "arguments and handles the rendering automatically. Compose " + "generously — a dashboard should feel like a real analytics product, " + "not a single widget.";/** * Dedicated agent for the A2UI dynamic-schema demo. Wires NO `generate_a2ui` * tool — the runtime's `injectA2UITool: true` makes the adapter auto-inject it * and drive a secondary render planner to GENERATE the surface. */export async function buildA2uiDynamicAgent(): Promise<StrandsAgent> { const strandsAgent = new Agent({ // Chat Completions API: the Responses adapter buffers tool-call argument // deltas, which would defeat A2UI's progressive surface streaming. model: await createModel({ openaiApi: "chat" }), systemPrompt: A2UI_DYNAMIC_SYSTEM_PROMPT, }); const config: StrandsAgentConfig = { a2ui: { defaultCatalogId: A2UI_DYNAMIC_CATALOG_ID, guidelines: { compositionGuide: A2UI_DYNAMIC_COMPOSITION_GUIDE }, }, }; return new StrandsAgent({ agent: strandsAgent, name: "a2ui_dynamic_schema", description: "Dynamic A2UI surfaces generated on the fly (auto-injected tool)", config, });}// ---------------------------------------------------------------------------// A2UI Error Recovery (a2ui-recovery) — adapter auto-injects + runs recovery.// ---------------------------------------------------------------------------//// Same auto-injected dynamic-schema setup as buildA2uiDynamicAgent, but the// aimock fixtures force the inner render_a2ui to emit free-form/sloppy args// (heal pill) or a structurally-invalid surface on every attempt (exhaust// pill). The Strands adapter runs the toolkit validate->retry recovery loop on// its auto-inject path (default 3 attempts) and returns the// a2ui_recovery_exhausted hard-fail envelope when the cap is hit — so this// agent wires NO tool, unlike the langgraph/ADK siblings (which own the tool// explicitly via getA2UITools + injectA2UITool:false). Mirrors the ag-ui dojo// aws-strands recovery example./** * Dedicated agent for the A2UI error-recovery demo. Wires NO `generate_a2ui` * tool — the runtime's `injectA2UITool: true` makes the adapter auto-inject it, * drive the secondary render planner, and run the recovery loop. */export async function buildA2uiRecoveryAgent(): Promise<StrandsAgent> { const strandsAgent = new Agent({ // Chat Completions API: the Responses adapter buffers tool-call argument // deltas, which would defeat A2UI's progressive surface streaming. model: await createModel({ openaiApi: "chat" }), systemPrompt: A2UI_DYNAMIC_SYSTEM_PROMPT, }); const config: StrandsAgentConfig = { a2ui: { defaultCatalogId: A2UI_DYNAMIC_CATALOG_ID, guidelines: { compositionGuide: A2UI_DYNAMIC_COMPOSITION_GUIDE }, }, }; return new StrandsAgent({ agent: strandsAgent, name: "a2ui_recovery", description: "Dynamic A2UI with automatic error recovery (auto-injected tool)", config, });}What is this?#
Tools are how an LLM invokes predefined, typically-deterministic functions. Tool rendering lets you decide how each of those tool calls appears in the chat. Instead of showing raw JSON, you register a React component that draws a branded card for the call (arguments, live status, and the eventual result). This is the Generative UI variant CopilotKit calls tool rendering.
Free course: See this pattern built end-to-end in Build Interactive Agents with Generative UI — a free DeepLearning.AI short course taught by CopilotKit's CEO covering the full Generative UI spectrum (Controlled, Declarative, and Open-Ended).
When should I use this?#
Render tool calls when you want to:
- Show users exactly what tools the agent is invoking and with what arguments
- Display live progress indicators while a tool executes
- Render rich, polished results once a tool completes
- Give tool-heavy agents a transparent, on-brand chat experience
Default tool rendering (zero-config)#
The simplest entry point: call useDefaultRenderTool() with no arguments.
CopilotKit registers its built-in DefaultToolCallRenderer as the *
wildcard: every tool call renders as a tidy status card (tool name, live
Running → Done pill, collapsible arguments/result) without you writing
any UI. Calls the agent makes in a row are grouped into one card; see
Grouping tool calls.
Without this hook the runtime has no * renderer and tool calls are
invisible; the user only sees the assistant's final text summary.
// Opt in to CopilotKit's built-in default tool-call card. Called with // no config so the package-provided `DefaultToolCallRenderer` is used // as the wildcard renderer — this is the "out-of-the-box" UI the cell // is meant to showcase. useDefaultRenderTool();Here's what the built-in status card looks like for each tool call:
/** * Agent factories for the Strands TypeScript showcase backend. * * `buildShowcaseAgent` is the single shared agent that serves the vast * majority of demos (the frontend differentiates each demo via * useFrontendTool / useRenderTool / useHumanInTheLoop / useAgentContext). * It mirrors the Python sibling's `build_showcase_agent` minus A2UI. * * The tool-free specialized agents (voice, byoc-hashbrown, byoc-json-render) * are mounted on dedicated sub-paths by `server.ts`. */import { readFileSync } from "node:fs";import { dirname, join } from "node:path";import { fileURLToPath } from "node:url";import { Agent, tool } from "@strands-agents/sdk";import { z } from "zod";import type { RunAgentInput } from "@ag-ui/core";import { StrandsAgent } from "@ag-ui/aws-strands";import type { StrandsAgentConfig } from "@ag-ui/aws-strands";import { A2UI_OPERATIONS_KEY, createSurface, updateComponents, updateDataModel,} from "@ag-ui/a2ui-toolkit";import { createModel } from "./model-factory";import { SHOWCASE_TOOLS } from "./tools";import { BoardStateStrandsAgent } from "./todo-state-sync";import { withStateContext, salesStateFromArgs, salesStateFromResult, notesStateFromArgs, stepsStateFromArgs, documentStateFromArgs, makeSubagentStateFromResult,} from "./state";import { SYSTEM_PROMPT, VOICE_SYSTEM_PROMPT, BYOC_HASHBROWN_SYSTEM_PROMPT, BYOC_JSON_RENDER_SYSTEM_PROMPT,} from "./prompts";export class ShowcaseStrandsAgent extends BoardStateStrandsAgent { override async *run(inputData: RunAgentInput) { // The adapter exposes context during model calls and restores history afterward. yield* super.run(withStateContext(inputData)); }}export async function buildShowcaseAgent( openaiApi: "chat" | "responses" = "chat",): Promise<StrandsAgent> { const config: StrandsAgentConfig = { toolBehaviors: { // The tool keeps the sales pipeline in appState; this snapshot, built // from the args, only carries it to the UI. Keep the call/result in // message snapshots too so completed threads can replay them. manage_sales_todos: { stateFromArgs: salesStateFromArgs, }, get_sales_todos: { stateFromResult: salesStateFromResult }, // Shared State (Read + Write) — notes panel. set_notes: { stateFromArgs: notesStateFromArgs }, // gen-ui-agent — live progress card driven by set_steps transitions. set_steps: { stateFromArgs: stepsStateFromArgs }, // shared-state-streaming — stream the document string into state. write_document: { stateFromArgs: documentStateFromArgs }, // Sub-agents — append a delegation entry carrying the actual output. research_agent: { stateFromResult: makeSubagentStateFromResult("research_agent"), }, writing_agent: { stateFromResult: makeSubagentStateFromResult("writing_agent"), }, critique_agent: { stateFromResult: makeSubagentStateFromResult("critique_agent"), }, }, }; const strandsAgent = new Agent({ model: await createModel({ openaiApi }), systemPrompt: SYSTEM_PROMPT, tools: SHOWCASE_TOOLS, }); return new ShowcaseStrandsAgent({ agent: strandsAgent, name: "strands_agent", description: "A polished CopilotKit demo assistant: chat, tools, shared state, HITL, sub-agents.", config, });}/** * Published Strands Chat Completions drops parallel call indices before native * aggregation. Responses preserves each call and emits complete, ordered blocks. * Rich chat intentionally buffers tool arguments; the shared agent keeps Chat * for demos that demonstrate progressive state and UI updates. */export function buildRichChatAgent(): Promise<StrandsAgent> { return buildShowcaseAgent("responses");}/** Tool-free agent for the voice demo (transcription + basic chat). */export async function buildVoiceAgent(): Promise<StrandsAgent> { const strandsAgent = new Agent({ model: await createModel(), systemPrompt: VOICE_SYSTEM_PROMPT, tools: [], }); return new StrandsAgent({ agent: strandsAgent, name: "voice_agent", description: "Simple assistant for the voice demo — no tools.", });}/** Tool-free hashbrown UI-kit envelope generator (declarative-hashbrown). */export async function buildByocHashbrownAgent(): Promise<StrandsAgent> { const strandsAgent = new Agent({ model: await createModel(), systemPrompt: BYOC_HASHBROWN_SYSTEM_PROMPT, tools: [], }); return new StrandsAgent({ agent: strandsAgent, name: "byoc_hashbrown", description: "Hashbrown UI-kit envelope generator for the declarative-hashbrown demo.", });}/** Tool-free json-render flat-spec generator (declarative-json-render). */export async function buildByocJsonRenderAgent(): Promise<StrandsAgent> { const strandsAgent = new Agent({ model: await createModel(), systemPrompt: BYOC_JSON_RENDER_SYSTEM_PROMPT, tools: [], }); return new StrandsAgent({ agent: strandsAgent, name: "byoc_json_render", description: "json-render flat-spec generator for the declarative-json-render demo.", });}// ---------------------------------------------------------------------------// A2UI Fixed Schema (declarative-generative-ui) — dedicated backend tool.// ---------------------------------------------------------------------------//// Unlike the dynamic A2UI demo (which relies on the adapter auto-injecting a// `generate_a2ui` tool to *generate* a surface), the fixed-schema demo wires a// single plain backend tool — `display_flight` — that returns the// `a2ui_operations` envelope (createSurface -> updateComponents ->// updateDataModel). The component tree is fixed and authored ahead of time// (./a2ui_schemas/flight_schema.json); only the *data* changes per call. The// runtime A2UIMiddleware detects the envelope in the tool result and paints.// No sub-agent, no generation, no `generate_a2ui` injection.//// The schema's component names + data paths must match the showcase frontend// catalog at src/app/demos/a2ui-fixed-schema/a2ui/{definitions,renderers,// catalog}.ts — catalog id `copilotkit://flight-fixed-catalog`. This mirrors// the canonical langgraph-python demo (src/agents/a2ui_fixed.py).const _A2UI_DIR = dirname(fileURLToPath(import.meta.url));const A2UI_FIXED_CATALOG_ID = "copilotkit://flight-fixed-catalog";const A2UI_FIXED_SURFACE_ID = "flight-fixed-schema";// Fixed, pre-authored component layout. Loaded from JSON so it can be authored// and reviewed independently of the agent code.const FLIGHT_SCHEMA: Array<Record<string, unknown>> = JSON.parse( readFileSync(join(_A2UI_DIR, "a2ui_schemas", "flight_schema.json"), "utf-8"),);const A2UI_FIXED_SYSTEM_PROMPT = "You help users find flights. When asked about a flight, call " + "`display_flight` exactly ONCE with origin, destination, airline, and " + 'price. Use short airport codes (e.g. "SFO", "JFK") for ' + 'origin/destination and a price string like "$289". The tool\'s return ' + "value is an A2UI surface descriptor — the flight card is already rendered " + "to the user; do NOT call `display_flight` again for the same trip and do " + "NOT repeat the flight details in text. After the tool returns, reply with " + "one short confirmation sentence and stop.";/** * Dedicated agent for the A2UI fixed-schema demo. Returns the envelope as a * plain OBJECT (not a JSON string): the Strands TS SDK wraps an object * tool-return in a `json` content block the adapter reads and re-stringifies * into the TOOL_CALL_RESULT the client A2UIMiddleware scans for * `a2ui_operations`. (A bare string return lands in no content block and the * result comes through empty — unlike the Python SDK, which wraps strings.) */export async function buildA2uiFixedSchemaAgent(): Promise<StrandsAgent> { const displayFlight = tool({ name: "display_flight", description: "Show a flight card for the given trip. Use short airport codes " + '(e.g. "SFO", "JFK") for origin/destination and a price string like ' + '"$289". After this tool returns, the flight card is already rendered ' + "to the user via the A2UI surface — do NOT call it again for the same " + "flight; reply with one short confirmation sentence and stop.", inputSchema: z.object({ origin: z.string().describe('Origin airport code, e.g. "SFO".'), destination: z.string().describe('Destination airport code, e.g. "JFK".'), airline: z.string().describe('Airline name, e.g. "United".'), price: z.string().describe('Price string, e.g. "$289".'), }), callback: ({ origin, destination, airline, price }) => ({ [A2UI_OPERATIONS_KEY]: [ createSurface(A2UI_FIXED_SURFACE_ID, A2UI_FIXED_CATALOG_ID), updateComponents(A2UI_FIXED_SURFACE_ID, FLIGHT_SCHEMA), updateDataModel(A2UI_FIXED_SURFACE_ID, { origin, destination, airline, price, }), ], }), }); const strandsAgent = new Agent({ // Chat Completions API: the Responses adapter buffers tool-call argument // deltas, which would defeat A2UI's progressive surface streaming. model: await createModel({ openaiApi: "chat" }), systemPrompt: A2UI_FIXED_SYSTEM_PROMPT, tools: [displayFlight], }); return new StrandsAgent({ agent: strandsAgent, name: "a2ui_fixed_schema", description: "A2UI surface from a fixed, pre-authored schema (direct backend tool)", });}// ---------------------------------------------------------------------------// A2UI Dynamic Schema (declarative-gen-ui) — adapter auto-injects generate_a2ui.// ---------------------------------------------------------------------------//// Unlike the fixed-schema demo (which wires a `display_flight` tool returning a// pre-authored envelope), the dynamic demo lets the agent *generate* the// surface layout on the fly. The Next.js route// (app/api/copilotkit-declarative-gen-ui/route.ts) sets// `a2ui: { injectA2UITool: true, defaultCatalogId: "declarative-gen-ui-catalog" }`;// the runtime forwards the flag, the Strands adapter auto-injects a// `generate_a2ui` tool and drives a secondary render planner. The// `config.a2ui` block below supplies the catalog id stamped into generated// surfaces and the composition guide that teaches the planner the page's// catalog. Mirrors the ag-ui dynamic-schema reference example.//// The compositionGuide MUST describe the catalog the page registers at// src/app/demos/declarative-gen-ui/a2ui/{definitions,renderers,catalog}.ts// (catalog id `declarative-gen-ui-catalog`): Card / StatusBadge / Metric /// InfoRow / PrimaryButton / PieChart / BarChart / DataTable, composed inside// the basic catalog's Row / Column / Text (`includeBasicCatalog: true`).//// Grounding dataset + composition rules are kept in spirit with the frontend// `sales-context.ts` (SALES_DATASET + COMPOSITION_RULES) the page registers via// `useAgentContext`. The frontend context steers the PRIMARY agent; this// compositionGuide is the channel the adapter feeds to the secondary// `render_a2ui` planner (it gets `guidelines`, not the frontend App Context),// so the planner is self-contained.const A2UI_DYNAMIC_CATALOG_ID = "declarative-gen-ui-catalog";const A2UI_DYNAMIC_SALES_DATASET = `Vantage Threads (fictional B2B apparel company) — Q2 sales data. Ground every visual in these numbers; invent only plausible details consistent with them.- Quarterly revenue: $4.2M (up 12% QoQ). New customers: 186 (up 8%). Win rate: 31% (down 2pts). Avg deal size: $22.6k (up 5%).- Revenue by region: North America $1.9M, EMEA $1.3M, APAC $720k, LATAM $280k.- Monthly revenue: Jan $1.21M, Feb $1.34M, Mar $1.65M, Apr $1.38M, May $1.42M, Jun $1.40M.- Reps (vs quota): Dana Whitfield 124%, Marcus Lee 108%, Priya Sharma 97%, Tom Okafor 88%, Elena Vasquez 71%.- At-risk: total $615k ARR across 3 accounts — Northwind Retail ($340k renewal, no contact 6 weeks; severity high), Cascadia Outfitters ($180k, champion left; severity medium), Atlas Goods ($95k, stalled legal review; severity medium).- Biggest account: Meridian Apparel Group — owner Dana Whitfield, region North America, ARR $612k, renewal Sep 30, last contact 3 days ago, health green, 4 open opportunities worth $210k.- Meridian revenue by product line: Outerwear $260k, Footwear $180k, Accessories $112k, Custom $60k.`;const A2UI_DYNAMIC_COMPOSITION_RULES = `Use ONLY these exact component names (the registered catalog — any other name fails to render): Card, Column, Row, Text, Metric, PieChart, BarChart, DataTable, StatusBadge, InfoRow, PrimaryButton. The single-value KPI tile component is named exactly "Metric" (NOT "MetricTile" or "MetricCard").Pick A2UI components by the shape of the question — never ask which chart the user wants:1. Overall snapshot / "sales dashboard" → a Column (gap 16) whose first child is a Row (gap 16) of 4 Metric components (each with trend + trendValue), followed by a Row with a PieChart (revenue by region) next to a BarChart (monthly revenue, all six months Jan-Jun). Do NOT wrap the dashboard in a surrounding Card — the charts carry their own card chrome. Do NOT use StatusBadge, DataTable, or InfoRow here.2. Rep / team performance → a Column (gap 16) with a Card containing a DataTable (columns: rep, attainment, pipeline) next to or above a BarChart of quota attainment % per rep — no StatusBadge or InfoRow.3. Risk / health checks → a Column (gap 16): first a Row (gap 16) of 3 Metric components (ARR at risk $615k trend down, accounts at risk 3, biggest exposure Northwind $340k), then a Row (gap 16) with one compact Card per at-risk account (title = account name, subtitle = ARR at stake) containing a StatusBadge (error for high severity, warning otherwise) above a one-line Text with the reason and the recommended next action — no DataTable or InfoRow.4. Single account/entity details → a Row (gap 16) with a Card of InfoRow facts (owner, region, ARR, renewal date, last contact) next to a PieChart of that account's revenue by product line — no DataTable or StatusBadge.5. Part-of-whole follow-ups → PieChart; trends or comparisons over time/categories → BarChart.Compose generously — a dashboard should feel like a real analytics product, not a single widget.`;const A2UI_DYNAMIC_COMPOSITION_GUIDE = `${A2UI_DYNAMIC_SALES_DATASET}\n\n${A2UI_DYNAMIC_COMPOSITION_RULES}`;// Mirrors the langgraph-python demo's a2ui_dynamic.py SYSTEM_PROMPT.const A2UI_DYNAMIC_SYSTEM_PROMPT = "You are the embedded sales analyst for Vantage Threads, the fictional " + "B2B apparel company described in your App Context. Answer every " + "business question by calling `generate_a2ui` to draw a rich visual " + "surface, and keep the chat reply to one short sentence.\n\n" + "Ground every number in the sales dataset from App Context — never " + "invent figures that contradict it. Follow the dashboard composition " + "rules from App Context when choosing components: pick the component " + "by the shape of the question (snapshot → composed KPI dashboard with " + "charts; team performance → table; risk → status badges; single " + "account → info rows; part-of-whole → pie; trend/comparison → bar). " + "Never ask the user which chart they want. `generate_a2ui` takes no " + "arguments and handles the rendering automatically. Compose " + "generously — a dashboard should feel like a real analytics product, " + "not a single widget.";/** * Dedicated agent for the A2UI dynamic-schema demo. Wires NO `generate_a2ui` * tool — the runtime's `injectA2UITool: true` makes the adapter auto-inject it * and drive a secondary render planner to GENERATE the surface. */export async function buildA2uiDynamicAgent(): Promise<StrandsAgent> { const strandsAgent = new Agent({ // Chat Completions API: the Responses adapter buffers tool-call argument // deltas, which would defeat A2UI's progressive surface streaming. model: await createModel({ openaiApi: "chat" }), systemPrompt: A2UI_DYNAMIC_SYSTEM_PROMPT, }); const config: StrandsAgentConfig = { a2ui: { defaultCatalogId: A2UI_DYNAMIC_CATALOG_ID, guidelines: { compositionGuide: A2UI_DYNAMIC_COMPOSITION_GUIDE }, }, }; return new StrandsAgent({ agent: strandsAgent, name: "a2ui_dynamic_schema", description: "Dynamic A2UI surfaces generated on the fly (auto-injected tool)", config, });}// ---------------------------------------------------------------------------// A2UI Error Recovery (a2ui-recovery) — adapter auto-injects + runs recovery.// ---------------------------------------------------------------------------//// Same auto-injected dynamic-schema setup as buildA2uiDynamicAgent, but the// aimock fixtures force the inner render_a2ui to emit free-form/sloppy args// (heal pill) or a structurally-invalid surface on every attempt (exhaust// pill). The Strands adapter runs the toolkit validate->retry recovery loop on// its auto-inject path (default 3 attempts) and returns the// a2ui_recovery_exhausted hard-fail envelope when the cap is hit — so this// agent wires NO tool, unlike the langgraph/ADK siblings (which own the tool// explicitly via getA2UITools + injectA2UITool:false). Mirrors the ag-ui dojo// aws-strands recovery example./** * Dedicated agent for the A2UI error-recovery demo. Wires NO `generate_a2ui` * tool — the runtime's `injectA2UITool: true` makes the adapter auto-inject it, * drive the secondary render planner, and run the recovery loop. */export async function buildA2uiRecoveryAgent(): Promise<StrandsAgent> { const strandsAgent = new Agent({ // Chat Completions API: the Responses adapter buffers tool-call argument // deltas, which would defeat A2UI's progressive surface streaming. model: await createModel({ openaiApi: "chat" }), systemPrompt: A2UI_DYNAMIC_SYSTEM_PROMPT, }); const config: StrandsAgentConfig = { a2ui: { defaultCatalogId: A2UI_DYNAMIC_CATALOG_ID, guidelines: { compositionGuide: A2UI_DYNAMIC_COMPOSITION_GUIDE }, }, }; return new StrandsAgent({ agent: strandsAgent, name: "a2ui_recovery", description: "Dynamic A2UI with automatic error recovery (auto-injected tool)", config, });}Custom catch-all#
Once you want on-brand chrome, pass a render function to
useDefaultRenderTool. It's a convenience wrapper around
useRenderTool({ name: "*", ... }): one wildcard renderer handles every
tool call, named or not:
// `useDefaultRenderTool` is a convenience wrapper around // `useRenderTool({ name: "*", ... })` — a single wildcard renderer // that handles every tool call not claimed by a named renderer. useDefaultRenderTool( { render: ({ name, parameters, status, result }) => ( <CustomCatchallRenderer name={name} parameters={parameters} status={status as CatchallToolStatus} result={result} /> ), }, [], );Here's the branded catch-all in action, where every tool call gets the same on-brand card:
/** * Agent factories for the Strands TypeScript showcase backend. * * `buildShowcaseAgent` is the single shared agent that serves the vast * majority of demos (the frontend differentiates each demo via * useFrontendTool / useRenderTool / useHumanInTheLoop / useAgentContext). * It mirrors the Python sibling's `build_showcase_agent` minus A2UI. * * The tool-free specialized agents (voice, byoc-hashbrown, byoc-json-render) * are mounted on dedicated sub-paths by `server.ts`. */import { readFileSync } from "node:fs";import { dirname, join } from "node:path";import { fileURLToPath } from "node:url";import { Agent, tool } from "@strands-agents/sdk";import { z } from "zod";import type { RunAgentInput } from "@ag-ui/core";import { StrandsAgent } from "@ag-ui/aws-strands";import type { StrandsAgentConfig } from "@ag-ui/aws-strands";import { A2UI_OPERATIONS_KEY, createSurface, updateComponents, updateDataModel,} from "@ag-ui/a2ui-toolkit";import { createModel } from "./model-factory";import { SHOWCASE_TOOLS } from "./tools";import { BoardStateStrandsAgent } from "./todo-state-sync";import { withStateContext, salesStateFromArgs, salesStateFromResult, notesStateFromArgs, stepsStateFromArgs, documentStateFromArgs, makeSubagentStateFromResult,} from "./state";import { SYSTEM_PROMPT, VOICE_SYSTEM_PROMPT, BYOC_HASHBROWN_SYSTEM_PROMPT, BYOC_JSON_RENDER_SYSTEM_PROMPT,} from "./prompts";export class ShowcaseStrandsAgent extends BoardStateStrandsAgent { override async *run(inputData: RunAgentInput) { // The adapter exposes context during model calls and restores history afterward. yield* super.run(withStateContext(inputData)); }}export async function buildShowcaseAgent( openaiApi: "chat" | "responses" = "chat",): Promise<StrandsAgent> { const config: StrandsAgentConfig = { toolBehaviors: { // The tool keeps the sales pipeline in appState; this snapshot, built // from the args, only carries it to the UI. Keep the call/result in // message snapshots too so completed threads can replay them. manage_sales_todos: { stateFromArgs: salesStateFromArgs, }, get_sales_todos: { stateFromResult: salesStateFromResult }, // Shared State (Read + Write) — notes panel. set_notes: { stateFromArgs: notesStateFromArgs }, // gen-ui-agent — live progress card driven by set_steps transitions. set_steps: { stateFromArgs: stepsStateFromArgs }, // shared-state-streaming — stream the document string into state. write_document: { stateFromArgs: documentStateFromArgs }, // Sub-agents — append a delegation entry carrying the actual output. research_agent: { stateFromResult: makeSubagentStateFromResult("research_agent"), }, writing_agent: { stateFromResult: makeSubagentStateFromResult("writing_agent"), }, critique_agent: { stateFromResult: makeSubagentStateFromResult("critique_agent"), }, }, }; const strandsAgent = new Agent({ model: await createModel({ openaiApi }), systemPrompt: SYSTEM_PROMPT, tools: SHOWCASE_TOOLS, }); return new ShowcaseStrandsAgent({ agent: strandsAgent, name: "strands_agent", description: "A polished CopilotKit demo assistant: chat, tools, shared state, HITL, sub-agents.", config, });}/** * Published Strands Chat Completions drops parallel call indices before native * aggregation. Responses preserves each call and emits complete, ordered blocks. * Rich chat intentionally buffers tool arguments; the shared agent keeps Chat * for demos that demonstrate progressive state and UI updates. */export function buildRichChatAgent(): Promise<StrandsAgent> { return buildShowcaseAgent("responses");}/** Tool-free agent for the voice demo (transcription + basic chat). */export async function buildVoiceAgent(): Promise<StrandsAgent> { const strandsAgent = new Agent({ model: await createModel(), systemPrompt: VOICE_SYSTEM_PROMPT, tools: [], }); return new StrandsAgent({ agent: strandsAgent, name: "voice_agent", description: "Simple assistant for the voice demo — no tools.", });}/** Tool-free hashbrown UI-kit envelope generator (declarative-hashbrown). */export async function buildByocHashbrownAgent(): Promise<StrandsAgent> { const strandsAgent = new Agent({ model: await createModel(), systemPrompt: BYOC_HASHBROWN_SYSTEM_PROMPT, tools: [], }); return new StrandsAgent({ agent: strandsAgent, name: "byoc_hashbrown", description: "Hashbrown UI-kit envelope generator for the declarative-hashbrown demo.", });}/** Tool-free json-render flat-spec generator (declarative-json-render). */export async function buildByocJsonRenderAgent(): Promise<StrandsAgent> { const strandsAgent = new Agent({ model: await createModel(), systemPrompt: BYOC_JSON_RENDER_SYSTEM_PROMPT, tools: [], }); return new StrandsAgent({ agent: strandsAgent, name: "byoc_json_render", description: "json-render flat-spec generator for the declarative-json-render demo.", });}// ---------------------------------------------------------------------------// A2UI Fixed Schema (declarative-generative-ui) — dedicated backend tool.// ---------------------------------------------------------------------------//// Unlike the dynamic A2UI demo (which relies on the adapter auto-injecting a// `generate_a2ui` tool to *generate* a surface), the fixed-schema demo wires a// single plain backend tool — `display_flight` — that returns the// `a2ui_operations` envelope (createSurface -> updateComponents ->// updateDataModel). The component tree is fixed and authored ahead of time// (./a2ui_schemas/flight_schema.json); only the *data* changes per call. The// runtime A2UIMiddleware detects the envelope in the tool result and paints.// No sub-agent, no generation, no `generate_a2ui` injection.//// The schema's component names + data paths must match the showcase frontend// catalog at src/app/demos/a2ui-fixed-schema/a2ui/{definitions,renderers,// catalog}.ts — catalog id `copilotkit://flight-fixed-catalog`. This mirrors// the canonical langgraph-python demo (src/agents/a2ui_fixed.py).const _A2UI_DIR = dirname(fileURLToPath(import.meta.url));const A2UI_FIXED_CATALOG_ID = "copilotkit://flight-fixed-catalog";const A2UI_FIXED_SURFACE_ID = "flight-fixed-schema";// Fixed, pre-authored component layout. Loaded from JSON so it can be authored// and reviewed independently of the agent code.const FLIGHT_SCHEMA: Array<Record<string, unknown>> = JSON.parse( readFileSync(join(_A2UI_DIR, "a2ui_schemas", "flight_schema.json"), "utf-8"),);const A2UI_FIXED_SYSTEM_PROMPT = "You help users find flights. When asked about a flight, call " + "`display_flight` exactly ONCE with origin, destination, airline, and " + 'price. Use short airport codes (e.g. "SFO", "JFK") for ' + 'origin/destination and a price string like "$289". The tool\'s return ' + "value is an A2UI surface descriptor — the flight card is already rendered " + "to the user; do NOT call `display_flight` again for the same trip and do " + "NOT repeat the flight details in text. After the tool returns, reply with " + "one short confirmation sentence and stop.";/** * Dedicated agent for the A2UI fixed-schema demo. Returns the envelope as a * plain OBJECT (not a JSON string): the Strands TS SDK wraps an object * tool-return in a `json` content block the adapter reads and re-stringifies * into the TOOL_CALL_RESULT the client A2UIMiddleware scans for * `a2ui_operations`. (A bare string return lands in no content block and the * result comes through empty — unlike the Python SDK, which wraps strings.) */export async function buildA2uiFixedSchemaAgent(): Promise<StrandsAgent> { const displayFlight = tool({ name: "display_flight", description: "Show a flight card for the given trip. Use short airport codes " + '(e.g. "SFO", "JFK") for origin/destination and a price string like ' + '"$289". After this tool returns, the flight card is already rendered ' + "to the user via the A2UI surface — do NOT call it again for the same " + "flight; reply with one short confirmation sentence and stop.", inputSchema: z.object({ origin: z.string().describe('Origin airport code, e.g. "SFO".'), destination: z.string().describe('Destination airport code, e.g. "JFK".'), airline: z.string().describe('Airline name, e.g. "United".'), price: z.string().describe('Price string, e.g. "$289".'), }), callback: ({ origin, destination, airline, price }) => ({ [A2UI_OPERATIONS_KEY]: [ createSurface(A2UI_FIXED_SURFACE_ID, A2UI_FIXED_CATALOG_ID), updateComponents(A2UI_FIXED_SURFACE_ID, FLIGHT_SCHEMA), updateDataModel(A2UI_FIXED_SURFACE_ID, { origin, destination, airline, price, }), ], }), }); const strandsAgent = new Agent({ // Chat Completions API: the Responses adapter buffers tool-call argument // deltas, which would defeat A2UI's progressive surface streaming. model: await createModel({ openaiApi: "chat" }), systemPrompt: A2UI_FIXED_SYSTEM_PROMPT, tools: [displayFlight], }); return new StrandsAgent({ agent: strandsAgent, name: "a2ui_fixed_schema", description: "A2UI surface from a fixed, pre-authored schema (direct backend tool)", });}// ---------------------------------------------------------------------------// A2UI Dynamic Schema (declarative-gen-ui) — adapter auto-injects generate_a2ui.// ---------------------------------------------------------------------------//// Unlike the fixed-schema demo (which wires a `display_flight` tool returning a// pre-authored envelope), the dynamic demo lets the agent *generate* the// surface layout on the fly. The Next.js route// (app/api/copilotkit-declarative-gen-ui/route.ts) sets// `a2ui: { injectA2UITool: true, defaultCatalogId: "declarative-gen-ui-catalog" }`;// the runtime forwards the flag, the Strands adapter auto-injects a// `generate_a2ui` tool and drives a secondary render planner. The// `config.a2ui` block below supplies the catalog id stamped into generated// surfaces and the composition guide that teaches the planner the page's// catalog. Mirrors the ag-ui dynamic-schema reference example.//// The compositionGuide MUST describe the catalog the page registers at// src/app/demos/declarative-gen-ui/a2ui/{definitions,renderers,catalog}.ts// (catalog id `declarative-gen-ui-catalog`): Card / StatusBadge / Metric /// InfoRow / PrimaryButton / PieChart / BarChart / DataTable, composed inside// the basic catalog's Row / Column / Text (`includeBasicCatalog: true`).//// Grounding dataset + composition rules are kept in spirit with the frontend// `sales-context.ts` (SALES_DATASET + COMPOSITION_RULES) the page registers via// `useAgentContext`. The frontend context steers the PRIMARY agent; this// compositionGuide is the channel the adapter feeds to the secondary// `render_a2ui` planner (it gets `guidelines`, not the frontend App Context),// so the planner is self-contained.const A2UI_DYNAMIC_CATALOG_ID = "declarative-gen-ui-catalog";const A2UI_DYNAMIC_SALES_DATASET = `Vantage Threads (fictional B2B apparel company) — Q2 sales data. Ground every visual in these numbers; invent only plausible details consistent with them.- Quarterly revenue: $4.2M (up 12% QoQ). New customers: 186 (up 8%). Win rate: 31% (down 2pts). Avg deal size: $22.6k (up 5%).- Revenue by region: North America $1.9M, EMEA $1.3M, APAC $720k, LATAM $280k.- Monthly revenue: Jan $1.21M, Feb $1.34M, Mar $1.65M, Apr $1.38M, May $1.42M, Jun $1.40M.- Reps (vs quota): Dana Whitfield 124%, Marcus Lee 108%, Priya Sharma 97%, Tom Okafor 88%, Elena Vasquez 71%.- At-risk: total $615k ARR across 3 accounts — Northwind Retail ($340k renewal, no contact 6 weeks; severity high), Cascadia Outfitters ($180k, champion left; severity medium), Atlas Goods ($95k, stalled legal review; severity medium).- Biggest account: Meridian Apparel Group — owner Dana Whitfield, region North America, ARR $612k, renewal Sep 30, last contact 3 days ago, health green, 4 open opportunities worth $210k.- Meridian revenue by product line: Outerwear $260k, Footwear $180k, Accessories $112k, Custom $60k.`;const A2UI_DYNAMIC_COMPOSITION_RULES = `Use ONLY these exact component names (the registered catalog — any other name fails to render): Card, Column, Row, Text, Metric, PieChart, BarChart, DataTable, StatusBadge, InfoRow, PrimaryButton. The single-value KPI tile component is named exactly "Metric" (NOT "MetricTile" or "MetricCard").Pick A2UI components by the shape of the question — never ask which chart the user wants:1. Overall snapshot / "sales dashboard" → a Column (gap 16) whose first child is a Row (gap 16) of 4 Metric components (each with trend + trendValue), followed by a Row with a PieChart (revenue by region) next to a BarChart (monthly revenue, all six months Jan-Jun). Do NOT wrap the dashboard in a surrounding Card — the charts carry their own card chrome. Do NOT use StatusBadge, DataTable, or InfoRow here.2. Rep / team performance → a Column (gap 16) with a Card containing a DataTable (columns: rep, attainment, pipeline) next to or above a BarChart of quota attainment % per rep — no StatusBadge or InfoRow.3. Risk / health checks → a Column (gap 16): first a Row (gap 16) of 3 Metric components (ARR at risk $615k trend down, accounts at risk 3, biggest exposure Northwind $340k), then a Row (gap 16) with one compact Card per at-risk account (title = account name, subtitle = ARR at stake) containing a StatusBadge (error for high severity, warning otherwise) above a one-line Text with the reason and the recommended next action — no DataTable or InfoRow.4. Single account/entity details → a Row (gap 16) with a Card of InfoRow facts (owner, region, ARR, renewal date, last contact) next to a PieChart of that account's revenue by product line — no DataTable or StatusBadge.5. Part-of-whole follow-ups → PieChart; trends or comparisons over time/categories → BarChart.Compose generously — a dashboard should feel like a real analytics product, not a single widget.`;const A2UI_DYNAMIC_COMPOSITION_GUIDE = `${A2UI_DYNAMIC_SALES_DATASET}\n\n${A2UI_DYNAMIC_COMPOSITION_RULES}`;// Mirrors the langgraph-python demo's a2ui_dynamic.py SYSTEM_PROMPT.const A2UI_DYNAMIC_SYSTEM_PROMPT = "You are the embedded sales analyst for Vantage Threads, the fictional " + "B2B apparel company described in your App Context. Answer every " + "business question by calling `generate_a2ui` to draw a rich visual " + "surface, and keep the chat reply to one short sentence.\n\n" + "Ground every number in the sales dataset from App Context — never " + "invent figures that contradict it. Follow the dashboard composition " + "rules from App Context when choosing components: pick the component " + "by the shape of the question (snapshot → composed KPI dashboard with " + "charts; team performance → table; risk → status badges; single " + "account → info rows; part-of-whole → pie; trend/comparison → bar). " + "Never ask the user which chart they want. `generate_a2ui` takes no " + "arguments and handles the rendering automatically. Compose " + "generously — a dashboard should feel like a real analytics product, " + "not a single widget.";/** * Dedicated agent for the A2UI dynamic-schema demo. Wires NO `generate_a2ui` * tool — the runtime's `injectA2UITool: true` makes the adapter auto-inject it * and drive a secondary render planner to GENERATE the surface. */export async function buildA2uiDynamicAgent(): Promise<StrandsAgent> { const strandsAgent = new Agent({ // Chat Completions API: the Responses adapter buffers tool-call argument // deltas, which would defeat A2UI's progressive surface streaming. model: await createModel({ openaiApi: "chat" }), systemPrompt: A2UI_DYNAMIC_SYSTEM_PROMPT, }); const config: StrandsAgentConfig = { a2ui: { defaultCatalogId: A2UI_DYNAMIC_CATALOG_ID, guidelines: { compositionGuide: A2UI_DYNAMIC_COMPOSITION_GUIDE }, }, }; return new StrandsAgent({ agent: strandsAgent, name: "a2ui_dynamic_schema", description: "Dynamic A2UI surfaces generated on the fly (auto-injected tool)", config, });}// ---------------------------------------------------------------------------// A2UI Error Recovery (a2ui-recovery) — adapter auto-injects + runs recovery.// ---------------------------------------------------------------------------//// Same auto-injected dynamic-schema setup as buildA2uiDynamicAgent, but the// aimock fixtures force the inner render_a2ui to emit free-form/sloppy args// (heal pill) or a structurally-invalid surface on every attempt (exhaust// pill). The Strands adapter runs the toolkit validate->retry recovery loop on// its auto-inject path (default 3 attempts) and returns the// a2ui_recovery_exhausted hard-fail envelope when the cap is hit — so this// agent wires NO tool, unlike the langgraph/ADK siblings (which own the tool// explicitly via getA2UITools + injectA2UITool:false). Mirrors the ag-ui dojo// aws-strands recovery example./** * Dedicated agent for the A2UI error-recovery demo. Wires NO `generate_a2ui` * tool — the runtime's `injectA2UITool: true` makes the adapter auto-inject it, * drive the secondary render planner, and run the recovery loop. */export async function buildA2uiRecoveryAgent(): Promise<StrandsAgent> { const strandsAgent = new Agent({ // Chat Completions API: the Responses adapter buffers tool-call argument // deltas, which would defeat A2UI's progressive surface streaming. model: await createModel({ openaiApi: "chat" }), systemPrompt: A2UI_DYNAMIC_SYSTEM_PROMPT, }); const config: StrandsAgentConfig = { a2ui: { defaultCatalogId: A2UI_DYNAMIC_CATALOG_ID, guidelines: { compositionGuide: A2UI_DYNAMIC_COMPOSITION_GUIDE }, }, }; return new StrandsAgent({ agent: strandsAgent, name: "a2ui_recovery", description: "Dynamic A2UI with automatic error recovery (auto-injected tool)", config, });}Grouping tool calls#
Agents often call several tools in a row. By default, CopilotKit collapses
each run of calls drawn by the built-in card from useDefaultRenderTool() into
one card that reads "Used 3 tools". While a call runs, the card names it
("Running read_file src/app.ts"), and opening it shows a row per call. Calls
drawn by your own renderers always show on their own and split the group
around them, unless the renderer opts in with group: true:
useDefaultRenderTool({ render: MyToolRow, group: true });Pick how calls show with toolCallDisplay on the message view:
// "grouped" (default) | "line" | "stacked" | "turn" | "separate"
<CopilotChat messageView={{ toolCallDisplay: "line" }} />| Display | What the user sees |
|---|---|
"grouped" | One card per run of calls, collapsed to "Used 3 tools". Opens to a row per call. |
"line" | The same grouping as a quiet line of text, like "Thought for 4 seconds". |
"stacked" | The latest call on top of a stack of the earlier ones. Opens into a card per call. |
"turn" | The agent works in the open, then everything before the reply folds into "Worked for 9s". |
"separate" | Every call gets its own card. |
To compare the displays side by side, run the
Tool call display stories
in the React Storybook. They play a scripted run through the real message view,
with a control to switch toolCallDisplay.
To restyle or replace the group, use the group slot of the tool-calls view
(it applies to the grouped, line and stacked displays):
// ToolTimeline: your component, given the group's `calls` and a `renderCall` function
<CopilotChat
messageView={{
assistantMessage: { toolCallsView: { group: ToolTimeline } },
}}
/>See CopilotChatToolCallGroup
for its props and an example replacement.
Per-tool renderers#
The most expressive path is one renderer per tool name. The primary
tool-rendering cell wires two: get_weather draws a branded
WeatherCard, search_flights draws a FlightListCard. Each renderer
receives the tool's parsed arguments, a live status, and (once the agent
returns) the result:
Tool inputs and results are separate#
In useRenderTool, parameters contains the inputs the agent sent to the
tool. It does not change into the tool's return value when status becomes
"complete". The completed output arrives separately as result, a string.
For a tool that returns JSON, parse that string before reading its fields.
For example, get_weather might receive { "location": "Paris" } and return
{ "temperature": 22 }. Read parameters.location for the requested city and
the parsed result.temperature for the temperature. Adding temperature to
the renderer's parameters schema does not copy it from the result.
If a card says complete but still shows placeholder details, check whether
those details come from parameters instead of the parsed result. Completion
reports that the tool returned; it does not fill the card's props for you.
The frontend pattern is the same for every backend. This shared, docs-only example includes every component, type, and helper that its renderers use:
export interface WeatherCardProps {
loading: boolean;
location: string;
temperature?: number;
humidity?: number;
windSpeed?: number;
conditions?: string;
}
export function WeatherCard({
loading,
location,
temperature,
humidity,
windSpeed,
conditions,
}: WeatherCardProps) {
return (
<article className="rounded-xl border p-4">
<h3 className="font-semibold">{location || "Weather"}</h3>
{loading ? (
<p>Fetching weather...</p>
) : (
<dl>
<div>
<dt>Conditions</dt>
<dd>{conditions ?? "--"}</dd>
</div>
<div>
<dt>Temperature</dt>
<dd>{temperature ?? "--"}°F</dd>
</div>
<div>
<dt>Humidity</dt>
<dd>{humidity ?? "--"}%</dd>
</div>
<div>
<dt>Wind</dt>
<dd>{windSpeed ?? "--"} mph</dd>
</div>
</dl>
)}
</article>
);
}export interface Flight {
airline?: string;
flight?: string;
depart?: string;
arrive?: string;
price_usd?: number;
}
export interface FlightListCardProps {
loading: boolean;
origin: string;
destination: string;
flights: Flight[];
}
export function FlightListCard({
loading,
origin,
destination,
flights,
}: FlightListCardProps) {
return (
<article className="rounded-xl border p-4">
<h3 className="font-semibold">
{origin || "?"} → {destination || "?"}
</h3>
{loading ? (
<p>Searching...</p>
) : (
<ul>
{flights.map((flight, index) => (
<li key={`${flight.flight ?? "flight"}-${index}`}>
{flight.airline ?? "--"} {flight.flight ?? ""}:{" "}
{flight.depart ?? "?"} → {flight.arrive ?? "?"}
{flight.price_usd !== undefined ? ` ($${flight.price_usd})` : ""}
</li>
))}
</ul>
)}
</article>
);
}export function parseJsonResult<T>(result: unknown): T {
if (!result) return {} as T;
try {
return (typeof result === "string" ? JSON.parse(result) : result) as T;
} catch {
return {} as T;
}
}"use client";
import { useRenderTool } from "@copilotkit/react-core/v2";
import { z } from "zod";
import { WeatherCard } from "../components/weather-card";
import { FlightListCard, type Flight } from "../components/flight-list-card";
import { parseJsonResult } from "../lib/parse-json-result";
interface WeatherResult {
city?: string;
temperature?: number;
humidity?: number;
wind_speed?: number;
conditions?: string;
}
interface FlightSearchResult {
origin?: string;
destination?: string;
flights?: Flight[];
}
export function ToolRenderers() {
useRenderTool(
{
name: "get_weather",
parameters: z.object({ location: z.string() }),
render: ({ parameters, result, status }) => {
const parsed = parseJsonResult<WeatherResult>(result);
return (
<WeatherCard
loading={status !== "complete"}
location={parameters?.location ?? parsed.city ?? ""}
temperature={parsed.temperature}
humidity={parsed.humidity}
windSpeed={parsed.wind_speed}
conditions={parsed.conditions}
/>
);
},
},
[],
);
useRenderTool(
{
name: "search_flights",
parameters: z.object({
origin: z.string(),
destination: z.string(),
}),
render: ({ parameters, result, status }) => {
const parsed = parseJsonResult<FlightSearchResult>(result);
return (
<FlightListCard
loading={status !== "complete"}
origin={parameters?.origin ?? parsed.origin ?? ""}
destination={parameters?.destination ?? parsed.destination ?? ""}
flights={parsed.flights ?? []}
/>
);
},
},
[],
);
return null;
}Mount the renderers anywhere beneath the same CopilotKit provider as your
chat. The renderer component returns no layout of its own; it registers the
two named renderers for tool calls in the chat:
"use client";
import { CopilotChat, CopilotKit } from "@copilotkit/react-core/v2";
import { ToolRenderers } from "./tool-renderers";
export default function Page() {
return (
<CopilotKit runtimeUrl="/api/copilotkit" agent="tool-rendering">
<ToolRenderers />
<CopilotChat agentId="tool-rendering" />
</CopilotKit>
);
}The name you pass to useRenderTool must match the tool name the agent
exposes; that's how the runtime routes the call to your component.
Per-tool renderers compose with a catch-all: named renderers claim the
"interesting" tools and a wildcard handles everything else. In the primary
cell, the same CustomCatchallRenderer from above catches get_stock_price
and roll_dice:
// Wildcard catch-all for anything that doesn't match a per-tool // renderer above. useDefaultRenderTool( { render: ({ name, parameters, status, result }) => ( <CustomCatchallRenderer name={name} parameters={parameters} status={status as CatchallToolStatus} result={result} /> ), }, [], );The backend tool definition#
The frontend renderer only sees what the agent sends down. Here's the
matching backend definition for get_weather: expose a tool named
get_weather, return structured data, and let the frontend renderer with
the same name paint the card.
export const getWeather = tool({ name: "get_weather", description: "Get current weather for a location.", inputSchema: z.object({ location: z.string().describe("The location to get weather for."), }), callback: ({ location }) => JSON.stringify(getWeatherImpl(location)),});