AG-UI adapter for @shadcn/helpers and an AG-UI example for Trace

[rscholz98]

Summary

Idea: give AG-UI the same first-class seat the AI SDK and TanStack AI already have in the chat tooling, in two small steps.

1. An @shadcn/helpers/ag-ui adapter that plugs the scripted-chat helper into any AG-UI consumer.
2. A Trace docs example that maps AG-UI events to Trace lines, next to the existing AI SDK examples.

I contribute to the AG-UI repo and would be happy to do the work if either is welcome. If neither fits the roadmap, the fallback is a community registry entry, and this discussion is the check before building that.

Why now

AG-UI is already inside the stack, just one layer down.

• TanStack AI uses AG-UI as its wire protocol and depends on @ag-ui/core. Its useChat sends RunAgentInput and consumes AG-UI events from any compatible server.
• The TanStack helper in packages/helpers/src/tanstack-ai/format.ts already encodes NeutralChunk to AG-UI events. The encoder is scoped to TanStack but the mapping itself is protocol level.
• Trace, Chat and Human in the Loop are documented against AI SDK parts only. Teams on AG-UI servers (LangGraph, Pydantic AI, Mastra, ADK, CrewAI and others ship AG-UI endpoints) have to work out the mapping themselves.

1. @shadcn/helpers/ag-ui

ChatFormat in packages/helpers/src/core/types.ts is documented as one implementation per framework. An AG-UI adapter would be a third one.

• createChat() returns the same chainable writer: stepStart, reasoning, tool, sourceUrl, text.
• chat.transport() returns a scripted AbstractAgent from @ag-ui/client. Anything that takes an AG-UI agent can replay the script: CopilotKit, TanStack AI through a local connection, or a hand-rolled subscriber.
• The NeutralChunk to AG-UI encoder moves from the TanStack adapter into core and both adapters share it. STEP_STARTED, REASONING_*, TOOL_CALL_*, TEXT_MESSAGE_* and RUN_* already have one-to-one chunk equivalents in the TanStack mapping.
• Same unsupported set as the TanStack adapter: files, sources and metadata are not streamed because AG-UI has no event for them.

Scope is roughly the size of the existing tanstack-ai folder, plus a docs page under @shadcn/helpers.

2. Trace example for AG-UI events

Trace is presentational, so this is docs only. The mapping is small and I would mirror the structure of the current Reasoning and Tool examples.

AG-UI events	Trace
STEP_STARTED / STEP_FINISHED	TraceLine with status="running" until finished
TOOL_CALL_START / TOOL_CALL_ARGS / TOOL_CALL_END / TOOL_CALL_RESULT	TraceCollapsible, title from the tool name, result in TraceCollapsibleContent
REASONING_START / REASONING_MESSAGE_CONTENT / REASONING_END	TraceCollapsible with the reasoning text as content
ACTIVITY_SNAPSHOT / ACTIVITY_DELTA	TraceLine per activity, TraceDescription for counts or durations
RUN_ERROR	TraceLine with status="error"
Sub-agent run (nested RUN_STARTED with a parent run id)	nested Trace inside TraceCollapsibleContent

Either as a page section "Works with AG-UI events" or as a note that Trace works with TanStack AI message parts and therefore with any AG-UI backend.

Questions

• Is a third helpers adapter something you would take, or do you prefer helpers to stay AI SDK and TanStack only?
• If the adapter is out of scope, would an AG-UI example on the Trace page still be welcome?
• If both are out of scope, I will publish the pieces as a community registry and submit a directory entry instead.