build-ag-ui-agent
Load this skill when building or fixing the agent server behind an AG-UI canvas: an endpoint that calls an LLM with the canvas's frontend tools and streams AG-UI events over SSE. Trigger on "build the
SKILL.mdplugins/standalone/ceh-ag-ui/skills/build-ag-ui-agent/SKILL.md
GitHubBuild the AG-UI agent server
The canvas owns what the user sees, and this server owns what the model sees. Most bugs in an AG-UI backend come from mixing the two up: building the model's history out of the UI's messages, or running a tool that belongs to the canvas. The work is done when every check in Procedure step 3 passes.
Procedure
1. Start from the bundled server
Start from ${CLAUDE_SKILL_DIR}/assets/agent-server/ (main.py, pyproject.toml). Copy it to
server/ beside the canvas's web/, keeping agent/ (the mock, still the fastest way to test a
component), and run uv run uvicorn main:app --port 8000 from server/, with the mock stopped.
The canvas's Vite proxy already points at that port, and AGENT_ORIGIN overrides it. It uses
Claude through the official anthropic SDK by default, with AGENT_MODEL defaulting to
claude-opus-5-5. For a different provider, keep the structure in the Rules below and swap only
run_claude.
2. Add a backend tool
This is for a tool the server runs itself, such as a database lookup the model needs before choosing a component:
async def lookup_orders(args: dict[str, Any]) -> str:
region = args.get("region")
if not isinstance(region, str): # eager streaming: the API did not validate this
return "error: region must be a string"
return json.dumps(await db.orders_by_region(region))
BACKEND_TOOLS["lookup_orders"] = (
"Order totals for one region. Call before showing order data.",
{
"type": "object",
"properties": {"region": {"type": "string"}},
"required": ["region"],
},
lookup_orders,
)
The loop runs it, streams TOOL_CALL_RESULT, and continues without a new run from the canvas. An
action with side effects the user should confirm first goes through
ceh-ag-ui:add-human-approval, not straight into BACKEND_TOOLS.
3. Verify
uv run python -c "import main"succeeds with no credentials, because the import makes no network call.- With credentials, run the canvas against the server:
- "show me a table of three fruits and their prices" places
show_tableand then gets a short acknowledgement. - A follow-up question in the same thread works. That confirms the transcript was appended, not rebuilt.
- Press Stop mid-render and send another message. The next run succeeds, which confirms rule 4.
- "show me a table of three fruits and their prices" places
- Without credentials, test the loop with a scripted stand-in for
client.beta.messages.streamthat yieldscontent_block_*events and a final message withstop_reason: "tool_use". Then confirm that each request'smessagesstarts with the previous request'smessages.
4. Harden before deploying
- Persist
THREADS. The template keeps them in memory, in one process (markedless-code:). A restart loses every conversation, and a second replica sees none of them. Store them keyed bythreadIdin Redis or Postgres. Store the transcript exactly as it was appended, because a thinking block changed on the way through storage is invalid. - CORS: the dev canvas goes through the Vite proxy. A deployed canvas calls the server directly,
so allow exactly its origin with FastAPI's
CORSMiddleware, never*alongside credentials. - Auth: decide who may start runs on a thread before exposing the endpoint.
threadIdis client-chosen, so a guessable id lets anyone read or continue someone else's conversation.
Rules
One request, one run
POST /agent RunAgentInput{threadId, runId, messages, tools, state, resume}
→ RUN_STARTED
→ TEXT_MESSAGE_START / CONTENT… / END (model text, streamed)
→ TOOL_CALL_START / ARGS… / END (model tool call, streamed)
→ TOOL_CALL_RESULT (only for tools the SERVER ran)
→ RUN_FINISHED or RUN_ERROR (exactly one, always last)
- Every run ends with exactly one
RUN_FINISHEDorRUN_ERROR. A stream that simply stops leaves the canvas spinning. The template wraps the whole loop, so any exception becomesRUN_ERROR, and nothing follows it. - Stream as you go. Map each model content block onto the matching AG-UI event as it arrives
(
content_block_start, thendelta, thenstop). Take each index's block kind from itscontent_block_startevent.
The six rules
- Keep the model's own transcript per thread, and append only what is new. AG-UI messages are
the UI's view. They carry no thinking blocks and are shaped differently from provider messages.
Rebuilding the provider history from them on every run edits the past: it drops Claude's
thinking blocks (which breaks the preserved-thinking check on current models) and restarts the
prompt cache every time. The template stores
Thread.transcriptkeyed bythreadId, appends the finalcontentof each response unchanged, and folds in only unseen AG-UI message ids. Those are new user text and the canvas's tool results. - Pass the canvas's tools through, and never run them.
run.toolsholds the catalogue. Send them to the model as tools. When the model calls one, stream the call and end the run. The canvas validates the call, renders it, and starts the next run with arole: "tool"message. - Answer every tool call in one user turn. When the model calls a backend tool and a frontend
tool in the same turn, run the backend one now, stream its
TOOL_CALL_RESULT, and hold itstool_result(Thread.held). Send it together with the canvas's results on the next run. Splitting one turn's results across two user messages is rejected by the API. - A call the canvas never answers still needs a result. The user can press Stop, or type
something new, before a component renders. On the next run, add an error
tool_resultfor every call inThread.awaitingthat has no answer. Otherwise the transcript has an unpairedtool_useand every later request fails. - The browser does not write the prompt. Ignore
systemanddevelopermessages from the client, and ignore assistant messages too, since the server produced those. The system prompt lives on the server. Treatrun.toolsdescriptions and schemas as untrusted input. They shape what the model does, so a deployed server should accept only the catalogue it expects, for example by comparing tool names against an allowlist. - Styling never enters the prompt. The system prompt tells the model the app fixes how components look. The canvas strips anything outside a schema anyway, but a model that keeps trying to style wastes turns.
Claude-specific choices in the template
The template follows claude-api defaults. When changing them, check that skill's current guidance
rather than recalling it:
- Streaming with
max_tokens=64000,effort: "medium"set explicitly. The default effort differs by model. Uselowfor a snappier chat andhighfor hard analysis. eager_input_streaming: Trueon every tool, so arguments stream intoTOOL_CALL_ARGSwhile they are generated. The trade-off is that the API no longer validates the input. The canvas validates frontend calls with zod, and backend handlers must validate their own input.fallbacks: "default"with theserver-side-fallback-2026-07-01beta, so a policy refusal is retried on a fallback model.echoable()keeps only the text from before a mid-output fallback block, as the API requires. A finalrefusalbecomesRUN_ERRORwithcode: "refusal".- Stop reasons, checked before acting:
max_tokenswith a tool call means the arguments were truncated, so end withRUN_ERRORand do not hand them to the canvas.pause_turnmeans loop again.tool_usemeans the tool rules above apply. - No forced
tool_choice. Current Claude models rejectanyandtool. Steer toward components in the system prompt instead.
Hands off to
- A backend tool whose side effects the user should confirm first:
ceh-ag-ui:add-human-approval. - A value the agent keeps updating while it works:
ceh-ag-ui:add-live-state-panel. - The canvas this server answers does not exist yet:
ceh-ag-ui:build-ag-ui.