Write your own AG-UI agent
Extend AG-UI's AbstractAgent, register it in the Copilot Runtime, and keep its fields across the runtime's per-request clone.
Your agent logic runs in the same process as the runtime, and it is not built
on a framework that CopilotKit integrates with. Subclass AG-UI's
AbstractAgent and register the instance in the runtime's agents map. The
framework adapters and HttpAgent are subclasses of AbstractAgent too.
If you only want to call a model with your own code, BuiltInAgent factory
mode is shorter: it emits the run lifecycle events for
you. If your agent is a separate service that already speaks AG-UI over HTTP,
use HttpAgent instead.
Install
Your @ag-ui/client must be the version your @copilotkit/runtime depends on,
so the app has one copy of it.
-
Install the packages:
npm install @copilotkit/runtime @ag-ui/client@1.0.2 rxjs -
Run
npm ls @ag-ui/client. It shows one deduped version. -
If it shows two versions, reinstall
@ag-ui/clientat the version listed under@copilotkit/runtime.
A minimal agent
A subclass implements run. It receives the AG-UI RunAgentInput (messages,
tools, context, state, threadId, runId) and returns an RxJS Observable of
AG-UI events. Start with RUN_STARTED, end with RUN_FINISHED, and stream the
reply in between:
import {
AbstractAgent,
EventType,
type BaseEvent,
type RunAgentInput,
} from "@ag-ui/client";
import { Observable } from "rxjs";
export class EchoAgent extends AbstractAgent {
run(input: RunAgentInput): Observable<BaseEvent> {
return new Observable<BaseEvent>((subscriber) => {
const { threadId, runId } = input;
const last = input.messages.at(-1);
const text = typeof last?.content === "string" ? last.content : "";
const messageId = crypto.randomUUID();
subscriber.next({ type: EventType.RUN_STARTED, threadId, runId });
subscriber.next({ type: EventType.TEXT_MESSAGE_START, messageId, role: "assistant" });
subscriber.next({ type: EventType.TEXT_MESSAGE_CONTENT, messageId, delta: `You said: ${text}` });
subscriber.next({ type: EventType.TEXT_MESSAGE_END, messageId });
subscriber.next({ type: EventType.RUN_FINISHED, threadId, runId });
subscriber.complete();
});
}
}Tool calls, state updates, and reasoning are more events on the same stream. See the AG-UI event reference.
Register it in the runtime
Pass an instance in the agents map. The key is the agent ID the frontend uses.
The chat components use default when you do not name an agent.
import {
CopilotRuntime,
createCopilotRuntimeHandler,
InMemoryAgentRunner,
} from "@copilotkit/runtime/v2";
import { EchoAgent } from "@/lib/echo-agent";
const runtime = new CopilotRuntime({
agents: { default: new EchoAgent() },
runner: new InMemoryAgentRunner(),
});
const handler = createCopilotRuntimeHandler({
runtime,
basePath: "/api/copilotkit",
});
export const GET = handler;
export const POST = handler;
export const PATCH = handler;
export const DELETE = handler;The agent runs inside the route handler's process. There is no separate agent server and no URL to configure. The frontend setup is the same as in the quickstart.
Open the chat and send hello. The agent replies You said: hello.
Override clone when the agent has its own fields
The runtime does not run the instance you registered. For every request it calls
agent.clone() and runs the copy, so per-request changes never touch the
original. See how agents slot into the runtime.
The base AbstractAgent.clone() copies only the fields AbstractAgent itself
defines, such as the agent ID, thread ID, messages, state, subscribers, and
middleware. It does not call your constructor. A field that your subclass sets in
its constructor, such as an API client, a URL, or a config object, is
undefined on the copy.
EchoAgent above has no fields of its own, so the base clone is enough. An
agent that takes a client in its constructor needs to copy it:
import {
AbstractAgent,
EventType,
type BaseEvent,
type RunAgentInput,
} from "@ag-ui/client";
import { Observable } from "rxjs";
export interface SupportClient {
answer(question: string, signal: AbortSignal): Promise<string>;
}
export class SupportAgent extends AbstractAgent {
constructor(private client: SupportClient) {
super();
}
override clone(): SupportAgent {
const copy = super.clone() as SupportAgent;
copy.client = this.client;
return copy;
}
run(input: RunAgentInput): Observable<BaseEvent> {
return new Observable<BaseEvent>((subscriber) => {
const controller = new AbortController();
const { threadId, runId } = input;
const last = input.messages.at(-1);
const question = typeof last?.content === "string" ? last.content : "";
subscriber.next({ type: EventType.RUN_STARTED, threadId, runId });
this.client
.answer(question, controller.signal)
.then((answer) => {
const messageId = crypto.randomUUID();
subscriber.next({ type: EventType.TEXT_MESSAGE_START, messageId, role: "assistant" });
subscriber.next({ type: EventType.TEXT_MESSAGE_CONTENT, messageId, delta: answer });
subscriber.next({ type: EventType.TEXT_MESSAGE_END, messageId });
subscriber.next({ type: EventType.RUN_FINISHED, threadId, runId });
subscriber.complete();
})
.catch((error) => subscriber.error(error));
return () => controller.abort();
});
}
}Start from super.clone() and add your fields to it, the same way HttpAgent
copies its url and headers. Do not return new SupportAgent(this.client):
a new instance starts with no middleware, so anything you attached with
agent.use(...) at startup silently stops running.
You only need to copy fields that hold configuration. A field that run resets
at the start of every run holds per-run scratch state, and losing it on the copy
changes nothing.
The function returned inside the Observable is its teardown. It runs when the
run completes, fails, or is unsubscribed, so it is the place to cancel in-flight
work.
The symptom when clone is missing
The registration succeeds and /info lists the agent, but every run fails as
soon as run touches the missing field. The server logs:
Agent execution failed: TypeError: Cannot read properties of undefined (reading 'answer')With InMemoryAgentRunner, the run's event stream ends with a RUN_ERROR
event that carries the same message and the code INCOMPLETE_STREAM. If the
error names one of your own constructor fields, add a clone override that
copies it.
Remote agents: use HttpAgent
If the agent runs as its own service and serves AG-UI over HTTP, do not write a
subclass. Register an HttpAgent that points at the service:
import { HttpAgent } from "@ag-ui/client";
import { CopilotRuntime, InMemoryAgentRunner } from "@copilotkit/runtime/v2";
const runtime = new CopilotRuntime({
agents: { default: new HttpAgent({ url: process.env.AGENT_URL! }) },
runner: new InMemoryAgentRunner(),
});HttpAgent already overrides clone. The URL is the agent service's own
endpoint, not the runtime's. See Copilot Runtime.
How is this guide?