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:
| 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
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:
- The runtime resolves the target agent by ID.
- It clones the agent for request isolation and supplies messages, state, and thread context.
AgentRunnerexecutes the agent and receives AG-UI events.- 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.
How is this guide?