# 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).

## Accessing your agent with `injectAgentStore` [#accessing-your-agent-with-injectagentstore]

`injectAgentStore` exposes the AG-UI agent and projects its messages, state,
and run status into Angular signals:

```ts title="src/app/agent-status.component.ts"
import { Component, computed } from "@angular/core";
import { injectAgentStore } from "@copilotkit/angular";

@Component({
  selector: "app-agent-status",
  template: `
    <p>{{ messageCount() }} messages</p>
    @if (store().isRunning()) {
      <p>Agent is running…</p>
    }
  `,
})
export class AgentStatusComponent {
  readonly store = injectAgentStore("research-agent");
  readonly messageCount = computed(() => this.store().messages().length);
}
```

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]

Subscribe to `store().agent` and release the subscription with the owning
injector:

```ts
private readonly destroyRef = inject(DestroyRef);
readonly store = injectAgentStore("research-agent");

constructor() {
  const subscription = this.store().agent.subscribe({
    onTextMessageContentEvent({ textMessageBuffer }) {
      console.log("Streaming text:", textMessageBuffer);
    },
    onToolCallEndEvent({ toolCallName, toolCallArgs }) {
      console.log("Tool called:", toolCallName, toolCallArgs);
    },
    onStateChanged({ agent }) {
      console.log("State changed:", agent.state);
    },
  });
  this.destroyRef.onDestroy(() => subscription.unsubscribe());
}
```

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.

```ts title="What your component sees"
const store = injectAgentStore("default");
const agent = store().agent;
store().messages();
store().state();
agent.subscribe({ /* … */ });
```

```ts title="What happens underneath"
// injectAgentStore() → registry checks /info → resolves a proxy agent
// core.runAgent({ agent }) → runtime POST → agent execution → SSE events
```

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