🐛 Bug: `HttpAgent.headers` are silently overwritten when the agent is registered via `agents__unsafe_dev_only`

[theodelobelle]

♻️ Reproduction Steps

1. Stand up a self-hosted AG-UI backend that requires an Authorization header (returns 401 without it).
2. Create an agent with a header and register it on the provider:

import { HttpAgent } from "@ag-ui/client";
import { CopilotKitProvider } from "@copilotkit/react-core/v2";

const agent = new HttpAgent({
  url: "http://localhost:XXXX/foundry-agent",
  headers: { Authorization: "Bearer <token>" }, // also try mutating agent.headers afterwards
});

<CopilotKitProvider agents__unsafe_dev_only={{ foundry: agent }}>
  {/* ...chat... */}
</CopilotKitProvider>

3. Send a message and inspect the outgoing request (Network tab / backend logs).

Observed: no Authorization header on the request; backend returns 401.
Workaround that works: drop the per-agent header and pass it via the provider prop instead:

<CopilotKitProvider
  headers={{ Authorization: "Bearer <token>" }}
  agents__unsafe_dev_only={{ foundry: agent }}
>

✅ Expected Behavior

One of:

• applyHeadersToAgent should merge the core headers into the agent's existing headers (agent.headers = { ...agent.headers, ...core.headers }) rather than replacing them, or
• the behavior should be clearly documented: "headers set on an HttpAgent passed to agents__unsafe_dev_only are ignored; use the CopilotKitProvider headers prop."

The silent overwrite with no warning is surprising and hard to debug (the request simply goes out without the header).

❌ Actual Behavior

agent.headers is replaced by { ...core.headers } at registration, so headers configured directly on the agent are dropped without any warning. The only working channel is the provider-level headers prop.

Screenshots

No response

𝌚 CopilotKit Version

├── @ag-ui/client@0.0.52
├── @copilotkit/react-core@1.56.2
├── @copilotkit/react-ui@1.56.2

📄 Logs (Optional)

[copilotkit-support-bot]

The bug you identified is indeed located in the AgentRegistry class within the @copilotkit/core package. Currently, the applyHeadersToAgent method completely replaces an agent's headers property with the global headers from the CopilotKitProvider (or CopilotKitCore), rather than merging them.

Details

Investigation Findings

In packages/core/src/core/agent-registry.ts, the implementation of applyHeadersToAgent is as follows:

/**
 * Apply current headers to an agent
 */
applyHeadersToAgent(agent: AbstractAgent): void {
  if (agent instanceof HttpAgent) {
    agent.headers = {
      ...(this.core as unknown as CopilotKitCoreFriendsAccess).headers,
    };
  }
}

As you observed, this logic takes the core headers and assigns them to agent.headers, discarding any headers previously configured on the HttpAgent instance. This happens during initial registration and whenever global headers are updated.

Proposed Solution

To fix this, the headers should be merged. Typically, agent-specific headers should take precedence over global provider headers:

applyHeadersToAgent(agent: AbstractAgent): void {
  if (agent instanceof HttpAgent) {
    agent.headers = {
      ...(this.core as unknown as CopilotKitCoreFriendsAccess).headers,
      ...agent.headers, // Agent-specific headers should override global ones
    };
  }
}

Path to Resolution

• Temporary Workaround: As you discovered, the only reliable way to pass headers currently is via the CopilotKitProvider's headers prop, as these are "pushed" to all registered agents.
• Official Fix: A PR is required to update packages/core/src/core/agent-registry.ts to perform a spread-merge instead of an assignment.
• Verification: The fix can be verified using the existing test suite in packages/core/src/__tests__/core-headers.test.ts, which already contains tests for header propagation but appears to miss the scenario where an agent starts with its own headers.

Confidence Assessment: High. The source code directly confirms the "silent overwrite" behavior described in the bug report.

Sources:

• AgentRegistry Source Code
• Header Tests

---

Was this helpful?

If this solution worked for you, please click on the appropriate option below to help us improve:

✅ This was helpful | ❌ Need more help