Proxied Copilot Runtime Agent
AG-UI agent that proxies a CopilotRuntime agent over REST, single-route, or Intelligence transports.
Overview
ProxiedCopilotRuntimeAgent is the AG-UI AbstractAgent implementation (extending HttpAgent) that CopilotKitCore uses to talk to a CopilotRuntime. You rarely construct this class. CopilotKitCore creates one for each runtime agent. To mount several frontend agents against one runtime agent, call registerProxiedAgent.
The agent builds the correct runtime URLs, picks the transport (rest, single, or auto-detected), and transparently delegates to an Intelligence agent when the runtime is in Intelligence mode.
Import
import { ProxiedCopilotRuntimeAgent } from "@copilotkit/core";Constructor
new ProxiedCopilotRuntimeAgent(config: ProxiedCopilotRuntimeAgentConfig)Prop
Type
Methods
Prop
Type
Usage
import { CopilotKitCore } from "@copilotkit/core";
const copilotkit = new CopilotKitCore({ runtimeUrl: "/api/copilotkit" });
// Mount a second frontend agent against the same runtime agent.
const { agent, unregister } = copilotkit.registerProxiedAgent({
agentId: "chat-1",
runtimeAgentId: "default",
});
await copilotkit.runAgent({ agent });
// On cleanup:
unregister();Behavior
- Transport auto-detection: with
transport: "auto", the agent issuesGET /info; a 2xx response selects REST, otherwise it falls back to single-route (POST { method: "info" }). - Lazy mode resolution: a
"pending"runtime mode is resolved by a runtime-info fetch before the firstrun()orconnect(). The agent then takes the HTTP path or the Intelligence path. - Intelligence delegation: in Intelligence mode the proxy creates an internal
IntelligenceAgentdelegate (websocket) and mirrors its messages, state, andisRunningback onto itself. - Immutable routing id:
runtimeAgentIdisreadonly; the REST run URL is baked at construction, so mutating it would desync routing. - Abort/Zod errors are swallowed:
AbortErrorand Zod validation errors complete the stream silently rather than propagating, so cancelling a run does not surface as an error.
How is this guide?