AG-UI · Getting Started

Introduction

Picking an adapter? This guide covers @threadplane/ag-ui — the AG-UI protocol adapter. If you're 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.

What is AG-UI?

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

See it live

The AG-UI demo runs this exact chat surface against an AG-UI backend — streaming, tool calls, and generative UI included. Compare it side by side with the LangGraph demo.

#How it fits

@threadplane/chat
  <chat>, <chat-message-list>, <chat-input>
  @threadplane/chat/debug -> <chat-debug>
      |
      | Agent contract (signals + events$)
      |
      +--> @threadplane/langgraph
      |      LangGraphAgent -> LangGraph Platform
      |
      +--> @threadplane/ag-ui
             toAgent(AbstractAgent) -> AG-UI backend

#What you get

  • toAgent(source: AbstractAgent): Agent - 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

Here's what the first release handles:

  • 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)

Out of scope for now (use @threadplane/langgraph if you need these):

  • Interrupts
  • Subagents
  • History / time-travel

#Next steps