Introduction

Picking an adapter? This guide covers @threadplane/ag-ui — the AG-UI protocol adapter. If you are talking to LangGraph Platform directly via the LangGraph SDK, use @threadplane/langgraph instead. See Choosing an adapter for a side-by-side comparison.

@threadplane/ag-ui is the runtime adapter that wraps an AG-UI AbstractAgent into the runtime-neutral Agent contract from @threadplane/chat. The chat UI primitives consume the Agent contract, and the AG-UI adapter translates between the contract and the AG-UI event protocol.

Note: What is AG-UI?

AG-UI is an open agent-to-UI protocol. It standardizes how agent runtimes stream events (messages, tool calls, state updates) to a frontend. It is used by CrewAI, Mastra, Microsoft Agent Framework, AG2, Pydantic AI, and AWS Strands. One adapter unlocks all of them.

Tip: See it live

The AG-UI demo runs this exact chat surface against an AG-UI backend — streaming, tool calls, and generative UI included.

Run AG-UI demo Compare LangGraph demo

How it fits

Backend speaks AG-UI over SSE → the adapter exposes the signal-shaped Agent contract → the chat UI renders.

What you get

toAgent(source: AbstractAgent): AgUiAgent - wraps any AbstractAgent subclass (custom transports, mocks) into the runtime-neutral Agent contract.
provideAgent({ url }) - DI convenience that instantiates HttpAgent under the hood for the common SSE/HTTP case.
FakeAgent - in-process AbstractAgent subclass that emits canned streaming events for offline demos and tests.

What's covered

This is what the adapter handles today:

messages (streaming token deltas via TEXT_MESSAGE_* events)
status / isLoading / error (lifecycle via RUN_STARTED/FINISHED/ERROR)
toolCalls (streaming tool calls via TOOL_CALL_* events)
state (snapshots and JSON-Patch deltas)
events$ (custom events; discriminates state_update)
Interrupts (from CUSTOM events named on_interrupt, or a RUN_FINISHED carrying an interrupt outcome)
Subagent progress (from SUBAGENT_* events, or ACTIVITY_* with activityType: 'subagent')

Out of scope for now (use @threadplane/langgraph if you need LangGraph Platform-specific APIs):

History / time-travel

Next steps

Quick Start - bind <chat> to an AG-UI backend in 5 minutes.
Installation - npm install + provider setup.
Architecture - understand the adapter boundary and provider choices.
Event Mapping - see how AG-UI events update Agent fields.
Fake Agent - build UI without a backend.
Citations - attach sources through state.citations.
Troubleshooting - debug provider, stream, state, and citation issues.
Chat Debug - inspect the raw event stream with <chat-debug>.