Skip to content

feat(react): answer interactive client tools in the Chat transcript - #1603

Open
blove wants to merge 3 commits into
mainfrom
blove/react-chat-client-tools
Open

blove wants to merge 3 commits into
mainfrom
blove/react-chat-client-tools

Conversation

@blove

@blove blove commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

What

React Chat can now show a tool the model calls and the person answers, the counterpart of the Angular chat clientTools input with ask tools.

const clientTools = createClientTools({
  pick_day: ask<{ days: string[] }, { day: string }>({
    description: 'Ask which itinerary day to plan.',
    render: ({ args, answer }) => <DayPicker days={args.days} onPick={(day) => answer({ day })} />,
  }),
});
// session: createSession({ ...options, tools: { ...clientTools.tools } })
<Chat session={session} clientTools={clientTools} />
  • ask() declares the tool; createClientTools() turns the declarations into core FunctionTools whose handler waits for the person, and keeps the waiting calls.
  • Chat takes the result as the opt-in clientTools prop. While a call waits, the app's view is drawn below the message's tool calls. The call keeps its row and its place in the tool group, so the group's progress, Stop and plan stay visible. The value passed to answer becomes the tool result, the view goes, and focus returns to the composer. Stop aborts the waiting call.
  • MessageList gains renderToolCallPrompt, a control drawn below a message's tool calls without replacing any of them. useClientToolCalls(clientTools) returns one for ask tools; usePendingClientToolCalls lists what waits.
  • The LangGraph cockpit client-tools example now uses this API: confirm_booking is an ask tool in src/booking.tsx, and the hand-rolled booking controller, decision tokens and approval slot wiring are gone. Its handler still checks arguments before the card shows, and disposal revokes a waiting booking.

What already existed

Both framework-neutral sessions (LangGraph and AG-UI) already declare and run FunctionTool handlers, including async ones, with follow-up and an optional execution store. What React lacked was the chat side: a way to draw a pending call as an answerable control. The cockpit example hand-rolled this for bookings with an app-owned controller and the approval slot.

Design notes

  • No change to AgentSession, @threadplane/core or either runtime. A handler receives only its arguments and an abort signal, not its call ID, so a waiting call is paired with the transcript call of the same name and equal arguments (else the oldest waiting call of that name). Identical calls are interchangeable, and a view always answers the arguments it was drawn with.
  • Off unless clientTools is set; no default changed.
  • verify-packages allow-lists the four new runtime exports of react/chat.

Left for later

  • Render-only view tools (today: a plain function tool plus renderToolCall).
  • Schema-derived argument types and validation; arguments reach render unvalidated.
  • A continuation limit (clientToolContinuationPolicy).
  • Built-in composer wording while an ask waits; the example sets its own placeholder from usePendingClientToolCalls.
  • The AG-UI cockpit client-tools example still hand-rolls its booking.
  • apps/website/public/media/docs/tools-react-capture.json records hashes of the example source from the last video capture; the demo video was not re-captured.
  • Passing the call ID to handlers would make pairing exact; that is a core ExecutionContext change and was not made here.

Verification

  • npx nx run-many -t test,type-tests,lint,build -p react,content,core: passed.
  • npx nx run-many -t test,lint -p cockpit-langgraph-client-tools-react,cockpit-registry: passed.
  • npx nx e2e cockpit-langgraph-client-tools-react: passed. This builds the isolated consumer with strict type checks and drives the example in Chromium against the local LangGraph fixture over real SDK HTTP and SSE: parallel identical bookings, focus, records, Stop, and the Trip group's progress and plan while the booking waits.
  • node scripts/react-parity/verify-packages.mjs: passed.
  • node scripts/react-parity/inventory.mjs --check --drift warn: valid (baseline drift is informational).
  • node --test scripts/react-parity/{verify-packages,runtime-consumer,inventory}.spec.mjs: 169 passed.
  • Website suite (docs page edited): 1988 of 1988 passed.
  • Mutation checks on client-tools.spec.tsx (14 specs), each red, restored tree green: prompt not rendered by MessageList; and, from the first commit, no focus return, renderer not refreshed when a call starts waiting, no argument pairing, abort ignored.
  • Not verified: no run against a deployed LangGraph or AG-UI backend with a live model; apps/website/e2e/react-client-tools-preview.spec.ts was not run locally.

AG-UI cockpit example

The AG-UI client-tools example (cockpit/ag-ui/client-tools/react) now declares confirm_booking with ask and createClientTools too (src/booking.tsx). Its controller keeps the check of the arguments and of the single running native call before the question is asked, and Stop, New conversation or unmount revokes a waiting booking. The decision tokens, the booking snapshot and respond() are removed, along with the re-check of the native call at answer time: the card is only drawn while Chat sees the call running.

Verified: example test (102) and lint, cockpit-registry test and lint, nx e2e cockpit-ag-ui-client-tools-react (25 passed, Chromium, local fixture), website suite (1988), cockpit script specs (50). Mutation check: without the disposal signal and the asked-once record, three specs fail.

🤖 Generated with Claude Code

Add ask() and createClientTools() to @threadplane/react/chat. An ask tool
becomes a core function tool whose handler waits for the person; Chat, through
the opt-in clientTools prop, shows the app-rendered view in place of the
pending call, returns the answer as the tool result and moves focus back to
the composer. MessageList gets the same through useClientToolCalls.

No session or core contract change: a handler is not told its call ID, so a
waiting call is paired with the transcript call by name and arguments.
@vercel

vercel Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
threadplane Ready Ready Preview Nov 16, 2026 5:14am UTC

Request Review

…ooking onto clientTools

A waiting ask tool no longer replaces its call's row. MessageList gains
renderToolCallPrompt, a control drawn below a message's tool calls, so the
call stays in its group and the group's progress, Stop and plan remain
visible. Chat wires clientTools through it, and useClientToolCalls now
returns a prompt renderer.

The LangGraph cockpit client-tools example declares confirm_booking with
ask and createClientTools (src/booking.tsx) in place of its hand-rolled
booking controller and approval-slot wiring.
The AG-UI client-tools example declares confirm_booking with ask and
createClientTools (src/booking.tsx). The controller still checks the
arguments and the running native call before the question is asked, and
Stop or disposal revokes a waiting booking. Tokens, the booking snapshot
and respond() are gone; Chat draws the card below the call through
clientTools.

This branch was successfully deployed

1 active deployment
Preview – threadplane — 64c227cd Deployed Nov 16, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant