# 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](https://ag-ui.com)
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 [#subscribing-to-ag-ui-events]

The callback names map directly to the [AG-UI event
types](https://docs.ag-ui.com/concepts/events):

| Event | Callback |
| --- | --- |
| Run lifecycle | `onRunStartedEvent`, `onRunFinishedEvent`, `onRunErrorEvent` |
| Steps | `onStepStartedEvent`, `onStepFinishedEvent` |
| Text messages | `onTextMessageStartEvent`, `onTextMessageContentEvent`, `onTextMessageEndEvent` |
| Tool calls | `onToolCallStartEvent`, `onToolCallArgsEvent`, `onToolCallEndEvent`, `onToolCallResultEvent` |
| State | `onStateSnapshotEvent`, `onStateDeltaEvent` |
| Messages | `onMessagesSnapshotEvent` |
| Custom | `onCustomEvent`, `onRawEvent` |
| High-level changes | `onMessagesChanged`, `onStateChanged` |

## The proxy pattern [#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 [#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:

```ts
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](/react-native/ag2/backend/custom-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](/ag2/quickstart) and the
<a href="https://docs.ag2.ai/docs/user-guide/ag-ui/" target="_blank">AG2 AG-UI integration docs</a>.

### 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
<a href="https://docs.ag2.ai/docs/user-guide/ag-ui/overview#capabilities" target="_blank">AG2 capabilities reference</a>.

Add a route that returns the document:

```python title="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.
