Proxy API

The Proxy API routes A2A requests through the Agent Explorer server, bypassing browser CORS restrictions.

Why Use the Proxy?

Browsers enforce CORS (Cross-Origin Resource Sharing) restrictions. If an agent doesn't allow cross-origin requests from your Agent Explorer origin, you'll see:

Access to fetch at 'https://agent.example.com' has been blocked by CORS policy

The proxy routes requests server-side, avoiding this restriction entirely.

Endpoint

POST /api/proxy

Request Format

{
  "url": "https://agent.example.com/message/send",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer token"
  },
  "body": {
    "jsonrpc": "2.0",
    "method": "message/send",
    "id": "1",
    "params": { "message": { ... } }
  }
}

Response

The proxy transparently returns the agent's response:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": { ... }
}

Headers Added by the Proxy

When you send a message from the chat window, the proxy attaches the protocol version you selected in the version dropdown:

Both version headers carry the same value — whichever version is active in the dropdown. Change the dropdown and the next message carries the new value.

Mock agents do not receive A2A-Version: they are addressed by a versioned URL (/api/mock-agents/:id/v1.0.0) and read x-a2a-protocol-version.

If your project defines a custom header with one of these names, the proxy's value takes precedence.

A2A-Version is not part of the A2A specification, which conveys protocol version via the AgentCard. Agent Explorer sends it for interoperability with live agents that expect a version header. Agents that ignore it are unaffected.

When to Use

• Direct requests fail with CORS errors
• The agent is on a different domain or localhost
• Testing during development

When NOT to Use

• The agent already supports CORS for your origin
• You need direct WebSocket connections
• Streaming SSE (streaming works better with direct connections)

Security Notes

• The proxy only forwards requests from authenticated users
• All proxied requests pass through your Agent Explorer server and are logged
• Do not use for production traffic volume — use it for testing only