Connect AG-UI agents

How CopilotKit connects any supported frontend and agent framework through AG-UI.

You can read every event that your agent streams, and you can connect any agent that speaks AG-UI. CopilotKit uses the AG-UI protocol for this. Agents send messages, state updates, tool calls, and lifecycle events to your app as Server-Sent Events (SSE).

The resolved agent is a standard AG-UI AbstractAgent. You can read its state, invoke protocol methods, and subscribe to its event stream.

Subscribing to AG-UI events

The callback names map directly to the AG-UI event types:

EventCallback
Run lifecycleonRunStartedEvent, onRunFinishedEvent, onRunErrorEvent
StepsonStepStartedEvent, onStepFinishedEvent
Text messagesonTextMessageStartEvent, onTextMessageContentEvent, onTextMessageEndEvent
Tool callsonToolCallStartEvent, onToolCallArgsEvent, onToolCallEndEvent, onToolCallResultEvent
StateonStateSnapshotEvent, onStateDeltaEvent
MessagesonMessagesSnapshotEvent
CustomonCustomEvent, onRawEvent
High-level changesonMessagesChanged, onStateChanged

The proxy pattern

When you use CopilotKit with a runtime, your frontend does not talk directly to the backend agent. CopilotKit discovers agents through the runtime's /info endpoint and represents each one with a proxy that implements the same AbstractAgent interface.

This indirection lets the runtime provide authentication, middleware, agent routing, and CopilotKit Intelligence without changing how the frontend interacts with agents.

How agents slot into the runtime

On the server, CopilotRuntime accepts a map of AG-UI AbstractAgent instances. For example, register an agent that runs on a remote AG-UI server:

import { CopilotRuntime } from "@copilotkit/runtime/v2";
import { HttpAgent } from "@ag-ui/client";

const runtime = new CopilotRuntime({
  agents: {
    my_agent: new HttpAgent({ url: "http://localhost:8000/" }),
  },
});

A framework adapter, an HttpAgent pointing at a remote server, and a custom implementation all use the same request path:

  1. The runtime resolves the target agent by ID.
  2. It clones the agent for request isolation and supplies messages, state, and thread context.
  3. AgentRunner executes the agent and receives AG-UI events.
  4. The runtime encodes those events as SSE and streams them to the frontend proxy.

The backend framework can change without forcing a corresponding change to the frontend AG-UI contract.

To write your own agent class, see Write your own AG-UI agent. That page also shows how to keep your custom fields when the runtime clones the agent in step 2.

Serve an AG2 agent over AG-UI

On the AG2 side, AGUIStream (from the ag2.ag_ui module, AG2 1.1.2+) exposes any agent as an AG-UI endpoint that CopilotKit consumes directly. See the quickstart and the AG2 AG-UI integration docs.

Serve the capabilities document

If you wrote your own @app.post("/chat") route, a GET to that endpoint returns 405. AG-UI clients use that GET to read what your agent supports. In AG2 1.1.2+, stream.build_asgi() answers it with a capabilities document (stream.capabilities()). With your own route, you add the GET route yourself.

The CopilotKit runtime does not request this document from an HttpAgent, so your CopilotKit app works without the GET route.

The document holds:

  • The agent identity.
  • Support for client-provided tools.
  • Support for state snapshots.
  • The named sub-agents.
  • Support for interrupts.

AG2 reads the document off the agent before any run starts. If AG2 does not know a value, it leaves that group out. AG-UI reads a missing group as "unknown". See the AG2 capabilities reference.

Add a route that returns the document:

run_ag_ui.py
from fastapi.responses import JSONResponse

@app.get("/chat")
async def capabilities() -> JSONResponse:
    # The same serialization `build_asgi()` uses: camelCase keys, unset groups left out.
    return JSONResponse(stream.capabilities().model_dump(by_alias=True, exclude_none=True))

If the /chat route checks a token, apply the same check to this route, so it does not describe your agent to anonymous callers.

How is this guide?