/** * Agents-as-tools example — client. * * Renders a single chat against the `Assistant` Think agent, with one * extra trick: while the assistant's `research` or `plan` tool is running, the * child agent it spawned (`Researcher` / `Planner`, themselves Think agents) * streams its chat chunks to the parent. The framework forwards those chunks on * the same WebSocket as `agent-tool-event` frames. `useAgentToolEvents` groups * them by the originating chat `toolCallId`, and the UI renders a mini-message * panel attached to the matching tool part. * * Architecture: * * useAgent ──▶ raw WS ──▶ useAgentToolEvents ──▶ AgentToolRunState[] * │ │ * ▼ ▼ * useAgentChat ──▶ messages[] (with tool parts) ──▶ * * Two stream sources, one connection, joined in the UI by toolCallId. * * The helper's chat chunks are AI SDK `UIMessageChunk` shapes — same * vocabulary `useAgentChat` uses for the assistant's main message. * `useAgentToolEvents` accumulates them per-helper into a parts array, * then we render those parts the same way the assistant's message renders. * * Per-helper drill-in is wired here via ``: clicking * the ↗ button on any helper panel opens a side panel that runs a * full `useAgentChat` against the helper's own sub-agent connection * (`useAgent({ agent: "Assistant", name: USER, sub: [{ agent: * helperType, name: runId }] })`). Because the helper IS a * Think, drill-in is real chat, not a custom event view — the * routing primitive does all the work. */ import { useCallback, useEffect, useMemo, useRef, useState } from "react"; import { useAgent, useAgentToolEvents } from "agents/react"; import { useAgentChat } from "@cloudflare/ai-chat/react"; import { getToolName, isToolUIPart, type UIMessage } from "ai"; import type { AgentToolRunState } from "agents/chat"; import { Badge, Button, Input, Surface, Text, PoweredByCloudflare } from "@cloudflare/kumo"; import { PaperPlaneRightIcon, MoonIcon, SunIcon, ChatCircleIcon, InfoIcon, GearIcon, XCircleIcon, CheckCircleIcon, CaretDownIcon, CaretRightIcon, RobotIcon, TrashIcon, ArrowSquareOutIcon, XIcon } from "@phosphor-icons/react"; import { Streamdown } from "streamdown"; import { code } from "@streamdown/code"; import { DEMO_USER } from "./protocol"; /** * Resolve the Assistant DO's "user name" for this page. Defaults to * `DEMO_USER` so the production demo is single-user; an optional * `?user=…` query param overrides it. * * The override is the hook the e2e suite uses to make tests * hermetic — Playwright opens each test against a fresh * `?user=test-` URL so each test gets its own Assistant DO, * which means no helper-row state leaks across tests AND the * "alarms inside facets lose `ctx.id.name` when the alarm fires * after the dev server restarts" framework gap can't bite us * (each test's DO is fresh — no in-flight alarms from a previous * session). * * Real users would never set this; production code should * authenticate the user and pass the canonical id explicitly. */ function resolveUser(): string { if (typeof window === "undefined") return DEMO_USER; const params = new URLSearchParams(window.location.search); return params.get("user") ?? DEMO_USER; } const USER = resolveUser(); /** * Helper class names that drill-in knows how to route to. Mirrors * the server's `helperClassByType` keys — adding a class server-side * means adding it here too. Using a set rather than a free string * lets `` render an explicit error state instead of * the silent "Connecting to helper…" hang we hit in 2026-04-28 * before the routing fix (and would still hit if a row ever stored * an unknown `helper_type`). */ const KNOWN_HELPER_TYPES: ReadonlySet = new Set([ "Researcher", "Planner" ]); type HelperParts = UIMessage["parts"]; /** * Per-helper accumulated state. Reconstructs the helper's growing * `UIMessage` from the forwarded chunk firehose, plus lifecycle metadata * (status, helperType, query, summary, error) from the parent's * synthesized `started`/`finished`/`error` events. */ type HelperState = { helperId: string; helperType: string; query: string; /** * Display order within a parent tool call's bucket. Set by the * `started` event the parent stamps from its dispatch position * (`compare` passes 0 for `a`, 1 for `b`). The renderer sorts by * this so panels appear left-to-right in the order the LLM * specified, not in race-determined arrival order. */ order: number; status: "running" | "done" | "error"; /** AI SDK `UIMessage.parts` reconstructed from agent-tool chunk events. */ parts: HelperParts; /** Final synthesized summary, set on `finished`. */ summary?: string; error?: string; }; function toHelperState(run: AgentToolRunState): HelperState { const label = run.display?.name ?? run.agentType; const preview = typeof run.inputPreview === "string" ? run.inputPreview : run.inputPreview === undefined ? "" : JSON.stringify(run.inputPreview); return { helperId: run.runId, helperType: label, query: preview, order: run.order, status: run.status === "completed" ? "done" : run.status === "running" ? "running" : "error", parts: run.parts, summary: run.summary, error: run.error }; } // ── Small UI helpers ─────────────────────────────────────────────── function ConnectionDot({ status }: { status: "connecting" | "connected" | "disconnected"; }) { const dot = status === "connected" ? "bg-green-500" : status === "connecting" ? "bg-yellow-500" : "bg-red-500"; return ; } function ModeToggle() { const [mode, setMode] = useState( () => localStorage.getItem("theme") || "light" ); useEffect(() => { document.documentElement.setAttribute("data-mode", mode); document.documentElement.style.colorScheme = mode; localStorage.setItem("theme", mode); }, [mode]); return ( {state.status === "running" ? ( Running ) : state.status === "done" ? ( Done ) : ( Error )} {onDrillIn && ( ); } // ── App ──────────────────────────────────────────────────────────── export default function App() { // One Assistant DO for this single-user demo. A real app would // authenticate first and use the user's id. const agent = useAgent({ agent: "Assistant", name: USER }); const { messages, sendMessage, clearHistory, status } = useAgentChat({ agent }); const agentTools = useAgentToolEvents({ agent }); const { runsByToolCallId, resetLocalState } = agentTools; const helperStateByToolCall = useMemo>(() => { return Object.fromEntries( Object.entries(runsByToolCallId).map(([toolCallId, runs]) => [ toolCallId, runs.map(toHelperState) ]) ); }, [runsByToolCallId]); // Drill-in side panel target. We store just the helper id; the // panel's metadata (helperType, query) is looked up from the // existing helper state. The panel itself opens its own // `useAgent({ sub: [...] })` connection to the helper; we don't // need to pre-resolve anything here. const [drillInHelperId, setDrillInHelperId] = useState(null); const openDrillIn = useCallback( (helperId: string) => setDrillInHelperId(helperId), [] ); const closeDrillIn = useCallback(() => setDrillInHelperId(null), []); // When messages.length drops to 0 (chat cleared in this tab or // another tab via `clearHistory`), reset all helper state too so // the panels disappear in lockstep with the messages they were // attached to. Also closes any open drill-in — the helper it was // pointing at has been deleted, and rendering would noop anyway. useEffect(() => { if (messages.length === 0) { resetLocalState(); setDrillInHelperId(null); } }, [messages.length, resetLocalState]); const [input, setInput] = useState(""); const send = useCallback( (e: React.FormEvent) => { e.preventDefault(); if (!input.trim()) return; sendMessage({ text: input }); setInput(""); }, [input, sendMessage] ); const clear = useCallback(() => { void (async () => { // Delete retained helper facets before broadcasting the chat // clear. Otherwise another tab could reconnect in the small // window between clearHistory() and helper-run cleanup and see // a replay of helper panels the user just cleared. try { await agent.call("clearHelperRuns"); } catch (err) { console.warn("[agents-as-tools] Failed to clear helper runs:", err); } clearHistory(); resetLocalState(); setDrillInHelperId(null); })(); }, [agent, clearHistory, resetLocalState]); const scrollRef = useRef(null); useEffect(() => { scrollRef.current?.scrollTo({ top: scrollRef.current.scrollHeight, behavior: "smooth" }); }, [messages.length]); const connectionStatus = agent.readyState === 1 ? "connected" : agent.readyState === 0 ? "connecting" : "disconnected"; return (

{/* ── Header ──────────────────────────────────────────────── */}

Agents as Tools

{/* ── Explainer ───────────────────────────────────────────── */}

Helper events stream live, inline Ask for research on a topic. The assistant calls the{" "} research tool, which spawns a{" "} Researcher sub-agent. The helper is itself a Think instance running its own inference loop; its chat stream is forwarded onto this WebSocket and rendered inline under the tool call as it runs.

{/* ── Message stream ──────────────────────────────────────── */}

{messages.length === 0 ? ( ) : ( messages.map((m) => (

{m.role}

)) )}

{/* ── Drill-in side panel ─────────────────────────────────── */} {drillInHelperId && (() => { // Find this helper's state to populate the panel header. // The map is `parentToolCallId → HelperState[]`, so we scan // buckets. The state is small: one entry per retained run in // the current chat history. let helperState: HelperState | undefined; for (const bucket of Object.values(helperStateByToolCall)) { helperState = bucket.find( (run) => run.helperId === drillInHelperId ); if (helperState) { break; } } if (!helperState) { // Helper id refers to a state that's been cleared or // never tracked — close cleanly. Shouldn't happen in // practice (drill-in is triggered from a panel that is // already in the state map). return null; } return ( ); })()} {/* ── Composer ───────────────────────────────────────────── */}

); } function EmptyHints() { return (

Try asking for research:

Research the top three Rust web frameworks and compare their throughput.
Find me three good arguments for and against monorepos.
What changed in HTTP/3 versus HTTP/2?
What are the key differences between OAuth 2.0 and OIDC?

Plain chat works too — the helper only spawns when the model decides to call the research tool.

); }