# 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/strands-typescript/backend/custom-ag-ui-agent).
That page also shows how to keep your custom fields when the runtime clones the
agent in step 2.
