# ProxiedCopilotRuntimeAgent

> AG-UI agent that proxies a CopilotRuntime agent over REST, single-route, or Intelligence transports.

## Overview [#overview]

`ProxiedCopilotRuntimeAgent` is the AG-UI [`AbstractAgent`](https://docs.ag-ui.com/sdk/js/client/abstract-agent) 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`](/reference/core/classes/CopilotKitCore).

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]

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

## Constructor [#constructor]

```ts
new ProxiedCopilotRuntimeAgent(config: ProxiedCopilotRuntimeAgentConfig)
```

<PropertyReference name="config" type="ProxiedCopilotRuntimeAgentConfig" required>
  Configuration object. Extends AG-UI's `HttpAgentConfig` (minus `url`). See [ProxiedCopilotRuntimeAgentConfig](/reference/core/types/ProxiedCopilotRuntimeAgentConfig).

  <PropertyReference name="runtimeUrl" type="string">
    Base URL of the CopilotRuntime. One trailing slash is removed before REST paths such as `/info` are joined. With `transport: "single"`, requests go to the URL exactly as you give it. Required when `transport` is `"single"`.
  </PropertyReference>

  <PropertyReference name="transport" type="CopilotRuntimeTransport" default="auto">
    Transport style: `"rest"`, `"single"`, or `"auto"` (probes REST then falls back to single-route).
  </PropertyReference>

  <PropertyReference name="runtimeAgentId" type="string">
    Runtime-side agent id to route outbound requests to. When set, the local `agentId` stays the registry key while traffic is routed to `runtimeAgentId`.
  </PropertyReference>

  <PropertyReference name="credentials" type="RequestCredentials">
    Credentials mode applied to runtime fetch requests.
  </PropertyReference>

  <PropertyReference name="runtimeMode" type='"sse" | "intelligence" | "pending"' default="sse">
    Runtime mode. `"pending"` means that the mode is not resolved yet. The agent fetches runtime info before its first request.
  </PropertyReference>

  <PropertyReference name="intelligence" type="IntelligenceRuntimeInfo">
    Intelligence runtime metadata (e.g. websocket URL) used to build the Intelligence delegate.
  </PropertyReference>

  <PropertyReference name="capabilities" type="AgentCapabilities">
    Advertised agent capabilities, returned by `capabilities` / `getCapabilities()`.
  </PropertyReference>

  <PropertyReference name="debug" type="ResolvedDebugConfig">
    Debug configuration applied to the agent.
  </PropertyReference>
</PropertyReference>

## Methods [#methods]

<PropertyReference name="run" type="(input: RunAgentInput) => Observable<BaseEvent>" required>
  Runs the agent against the runtime, returning the AG-UI event stream. Routes via HTTP, single-route, or the Intelligence delegate depending on the resolved runtime mode.
</PropertyReference>

<PropertyReference name="connect" type="(input: RunAgentInput) => Observable<BaseEvent>" required>
  Connects to the runtime agent to receive its event stream without starting a new run.
</PropertyReference>

<PropertyReference name="connectAgent" type="(parameters?, subscriber?) => Promise<RunAgentResult>" required>
  Higher-level connect that resolves the result and, in Intelligence mode, bridges the delegate's messages, state, and run lifecycle back onto this proxy.
</PropertyReference>

<PropertyReference name="abortRun" type="() => void" required>
  Aborts the active run. In Intelligence mode, aborts the delegate and detaches the local run pipeline; in HTTP (`rest`/`single`) mode, sends a stop request to the runtime. No-op when the agent has no `agentId`/`threadId` or no `fetch` is available.
</PropertyReference>

<PropertyReference name="detachActiveRun" type="() => Promise<void>" required>
  Detaches the currently attached run pipeline (and the delegate's, if present) without aborting the underlying run.
</PropertyReference>

<PropertyReference name="getCapabilities" type="() => Promise<AgentCapabilities>" required>
  Resolves the agent's advertised capabilities (empty object if none were configured).
</PropertyReference>

<PropertyReference name="clearReplayCursor" type="(threadId: string) => void" required>
  In Intelligence mode, drops the delegate's cached event cursor for a thread so the next connect replays full history. No-op for other runtime modes.
</PropertyReference>

<PropertyReference name="clone" type="() => ProxiedCopilotRuntimeAgent" required>
  Returns a new, independent instance carrying over runtime URL, ids, transport, mode, capabilities, headers, messages, and state. `state` and `messages` are deep-cloned, so mutating the clone does not affect the original; the delegate, if present, is cloned via its own `clone()`.
</PropertyReference>

<PropertyReference name="capabilities" type="AgentCapabilities | undefined" required>
  Read-only. The configured capabilities, or `undefined`.
</PropertyReference>

<PropertyReference name="runtimeAgentId" type="string | undefined" required>
  Read-only. The runtime-side agent id outbound requests are routed to, when configured.
</PropertyReference>

## Usage [#usage]

```ts
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 [#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 by a runtime-info fetch before the first `run()` or `connect()`. The agent then takes the HTTP path or the Intelligence path.
- **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.
