ProxiedCopilotRuntimeAgent

Overview

ProxiedCopilotRuntimeAgent is the AG-UI AbstractAgent implementation (extending HttpAgent) that CopilotKitCore uses to talk to a CopilotRuntime. It 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. You rarely construct it directly — CopilotKitCore creates one per runtime agent — but you reach for it (via registerProxiedAgent) when mounting several frontend agents against a single runtime agent.

Import

import { ProxiedCopilotRuntimeAgent } from "@copilotkit/core";

Constructor

new ProxiedCopilotRuntimeAgent(config: ProxiedCopilotRuntimeAgentConfig)

Methods

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 issues GET /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 via a runtime-info fetch only when the agent enters the Intelligence delegate path; plain HTTP run/connect proceed without resolving it.
• Intelligence delegation — in Intelligence mode the proxy creates an internal IntelligenceAgent delegate (websocket) and mirrors its messages, state, and isRunning back onto itself.
• Immutable routing id — runtimeAgentId is readonly; the REST run URL is baked at construction, so mutating it would desync routing.
• Abort/Zod errors are swallowed — AbortError and Zod validation errors complete the stream silently rather than propagating, so cancelling a run does not surface as an error.

Related

• @copilotkit/core overview
• CopilotKitCore
• ProxiedCopilotRuntimeAgentConfig
• AG-UI AbstractAgent