A2A Support in the API Platform

[RakhithaRR]

What problem are we solving, and why now?

Enterprises are deploying AI agents — their own and third-party — that increasingly call each other over the Agent2Agent (A2A) protocol to delegate tasks. Today a platform/API team has no consistent way to put these agent-to-agent interactions under governance: each agent re-implements its own auth, there is no central identity, authorization ("which agent may call which"), rate limiting, or cost control, and no end-to-end visibility across a multi-agent call chain. Teams want to govern A2A agents the way they already govern their other agent traffic, without modifying agent code.

A2A is now stable. A2A reached v1.0 under the Linux Foundation — its first stable release. The earlier 0.2.x/0.3.x versions changed rapidly and introduced breaking changes, making it risky to build durable gateway support against them; v1.0 provides a stable, vendor-neutral contract we can implement against with confidence. The AI Gateway governs enterprise agent traffic (LLM access, MCP tools), configured through AI Workspace; A2A is the agent-to-agent pillar and is currently the gap.

Who are we solving it for?

Primarily platform / API teams and agent developers in enterprises adopting multi-agent systems, and their security & compliance stakeholders who must audit and constrain agent interactions. Secondarily, the agents themselves (internal systems acting as callers) that need a stable, governed endpoint to reach other agents.

Solution

Introduce a new proxy type (a2aproxy) in the gateway and the AI Workspace to onboard agents.

flowchart LR
    subgraph CP["Control Plane — AI Workspace"]
        REG["A2A agent onboarding · policies<br/>security config · analytics"]
    end

    CLIENT["A2A clients /<br/>calling agents"]

    subgraph DP["Data Plane — AI Gateway"]
        GW["a2aproxy<br/>• Agent Card mediation<br/>• Transports: JSON-RPC / HTTP+JSON<br/>• Authentication<br/>• Rate limiting<br/>• Guardrails<br/>• Analytics & observability"]
    end

    UP["Upstream A2A agents<br/>(A2A v1.x)"]

    REG <-->|"config · sync"| GW
    CLIENT -- "A2A request<br/>(JSON-RPC / HTTP+JSON, SSE)" --> GW
    GW -- "forward request" --> UP

Loading

The platform will support the following capabilities:

• Agent Card mediation — fetch the upstream card and rewrite the required fields such as URLs, securityRequirements, skills, etc. based on the user requirements.
• Transport support — JSON-RPC and HTTP+JSON transports, with the option to transform between the two transports through a policy.
• Authentication — terminate and validate the caller credentials across the scheme(s) declared in the card (OAuth2/OIDC, API key, etc.).
• Rate limiting — per-agent / per-consumer quotas and throttling.
• Guardrails — content inspection on agent messages (prompt-injection, PII).
• Analytics & observability — OTel traces and analytics of agent usage.

User Stories

As an agent developer, I want to publish a rewritten Agent Card at the gateway's own well-known URL, so that clients discover the gateway endpoint and all traffic flows through governance.

Acceptance Criteria

• Onboarding with a reachable v1.x Agent Card URL + base path creates an active, gateway-fronted A2A proxy.
• The AI Workspace allows users to modify the Agent Card. It will also validate the upstream agent card and make sure it adheres to the schema.
• Once deployed, the agent card is reachable through /.well-known/agent-card.json relative to the base path of the A2A proxy created, with the URLs rewritten to the gateway address.

As an A2A client developer, I want to call the agent over either the JSON-RPC or the HTTP+JSON binding, so that I can use whichever transport my A2A SDK supports.

Acceptance Criteria

• The gateway will handle requests to the / path as well as specific REST endpoints based on the transport protocol used.

As an agent developer, I want the gateway to authenticate every caller against a declared scheme before forwarding, so that only authorized clients can reach an agent.

Acceptance Criteria

• A request with a missing or invalid credential is rejected with 401 before it reaches the backend.
• A request with a valid credential for a declared scheme is forwarded.
• The enforced scheme matches the one advertised in the published card.

As an agent developer, I want the public Agent Card to expose only non-sensitive metadata, so that discovery does not leak internal endpoints or sensitive skills.

Acceptance Criteria

• The published public card contains no internal/upstream URLs or secrets.
• Richer/sensitive detail is available only via the authenticated extended card.

As a security & compliance officer, I want the gateway to verify and optionally re-sign Agent Card signatures, so that clients can trust the card was not tampered with.

Acceptance Criteria

• If the upstream card is signed, the gateway verifies the signature against configured trust and rejects/flags an invalid one.
• When re-signing is enabled, the published card carries a valid gateway JWS verifiable against the gateway's published JWKS.

As an agent developer, I want to apply rate limits, so that expensive A2A operations can be constrained independently of cheap ones.

Acceptance Criteria

• Requests exceeding the configured limit receive 429; requests under the limit pass.
• The limit key is configurable (per agent, per consumer, per subscription).
• A limit can be keyed on the operation (e.g., SendMessage vs tasks/get) and enforced independently.

As an agent developer, I want end-to-end traces and per-agent metrics for A2A traffic, so that I can monitor and troubleshoot multi-agent interactions.

Acceptance Criteria

• Each A2A request produces an OTel span carrying gen_ai.agent.id and the A2A operation.
• Per-agent request count, latency, and error-rate metrics appear in AI Workspace analytics alongside LLM/MCP.
• Each call records consumer identity, target agent, operation, timestamp, and outcome (success/blocked/error).

Challenges

• A2A authentication scheme supports AND and OR conditions — i.e. you can define multiple schemes and enforce allOf or anyOf sort of scenarios. Need to check whether we can support such scenarios through our policy approach.
• The Agent Card discovery is done through a well-known URL. According to the standards, this has to come relative to the authority root, not with a base path. We cannot support this when we have multiple A2A proxies, as we use base paths to distinguish between proxies. This will have to be relative to the base path, similar to how we handle MCP proxies.
• There's a requirement for an agent registry, but a standard approach is still under discussion (Agent Registry - Proposal a2aproject/A2A#741).
• The gateway should expose a JWKS URL for the signed agent cards to be validated by the A2A clients.

Card Mediation: acquisition, computation, and curation

The gateway serves a rewritten Agent Card, not the upstream one — supportedInterfaces[].url rewritten to the gateway, securitySchemes/securityRequirements derived from the attached frontend-auth policy, upstream security stripped, and (optionally) re-signed with the gateway key + published JWKS.

Card mediation is a system policy. The gateway applies it automatically to every kind: A2a proxy — producing the card and serving it (plus the JWKS route) at the well-known path. It is not listed in the policies array and never appears in user-authored YAML. The only user-facing knob is whether to re-sign, exposed as a spec field (signCard); the JWKS route is published automatically when signing is on.

Acquisition: live proxy-and-rewrite vs. snapshot-and-serve

Two fundamentally different ways to obtain and maintain the served card.

Option 1 — Live proxy-and-rewrite. The gateway proxies the well-known path to the upstream at request time and rewrites the card's URLs on the fly (gateway address from X-Forwarded-*).

• Pros: always fresh; nothing stored; no drift (because nothing is cached).
• Cons: discovery availability is coupled to upstream uptime; no curation/editing; no devportal catalog; the gateway doesn't "hold" the document, so validation/guardrails on it are harder; and signing is paid per request — because the card is rewritten on the fly and can't be safely cached, enabling signCard forces a full JWS operation (canonicalization + signature) on every discovery request, a hot path clients hit before every session.

Option 2 — Snapshot-and-serve at deploy time (recommended). The card is fetched once, snapshotted into the deployed config, and the controller computes the served card at deploy, serving it from a local, non-forwarding (synth) route at /{context}/.well-known/agent-card.json (the same pattern used for MCP's OAuth Protected Resource Metadata).

• Pros: enables editing/curation and devportal publishing; deploy decoupled from upstream availability; signs once at deploy and serves a static, pre-signed document (zero per-request crypto); consistent across replicas.
• Cons: introduces drift (served card reflects snapshot time, not now) → requires a re-sync workflow.

Signing tilts the decision. Since we've committed to signed cards + a JWKS endpoint, per-request re-signing (Option 1) is wasted CPU on a hot path; sign-once-at-deploy (Option 2) is strictly cheaper. Combined with curation and devportal needs, Option 2 is the recommendation.

How the served card is computed (Option 2)

The pushed kind: A2a spec carries inputs + curation, not a frozen card:

Field	Role
agentCardUrl / snapshot	source card
policies	derive securitySchemes / securityRequirements + skill visibility
cardOverrides	curation: descriptions, tags, hidden skills, public/extended split
signCard	whether to re-sign

The controller computes the served card at deploy — identically for AI Workspace and gateway-only:

pushed spec ─► 1. take snapshot (or fetch)
              2. rewrite URLs → gateway        ← must be controller-side (needs runtime gateway host)
              3. derive security from policies
              4. apply skill visibility
              5. apply cardOverrides
              6. re-sign + publish JWKS         ← must be controller-side (needs gateway signing key)
           ─► served card @ /{context}/.well-known/agent-card.json

Why the controller computes it (not AI Workspace): URL rewriting needs the runtime gateway address and re-signing needs the gateway's signing key — neither exists in the control plane. Since those steps are inherently gateway-side, all derivation lives in the controller. AI Workspace's role is to author the spec and preview; the controller turns the spec into the served card. This keeps both authoring modes behaviorally identical.

Authoring modes

Recommended — agentCardUrl (AI Workspace auto-snapshots; gateway-only fetches at deploy). The user supplies agentCardUrl; the controller derives everything a hand-authored card would spell out — the rewritten supportedInterfaces[].url (from context + gateway host) and securitySchemes/securityRequirements (from the jwt-auth policy). No agentCard block needed in the common case.

apiVersion: gateway.api-platform.wso2.com/v1
kind: A2a
metadata:
  name: weather-agent-v1.0
spec:
  displayName: Weather Agent
  context: /weather
  specVersion: "1.0"
  signCard: true                                   # gateway re-signs; JWKS route auto-exposed
  agentCardUrl: http://weather:9001/.well-known/agent-card.json   # controller fetches + rewrites
  upstream:
    url: http://weather:9001
    auth:
      type: bearer
      header: Authorization
      value: "{{ secret weather-backend-token }}"
  policies:
    - { name: jwt-auth,      version: v1, params: { issuers: ["https://idp.example.com"], requiredScopes: ["a2a.invoke"] } }
    - { name: a2a-ratelimit, version: v1, params: { limit: 100, unit: minute, key: consumer } }

Gateway-only override — inline agentCard (a hand-authored snapshot). For air-gapped / no-egress deployments where the controller can't fetch upstream, the operator supplies the card inline; the controller still URL-rewrites and signs it. In AI Workspace this inline card is produced automatically as a snapshot (stored with the curation overrides) — the operator never hand-writes it.

apiVersion: gateway.api-platform.wso2.com/v1
kind: A2a
metadata:
  name: weather-agent-v1.0
spec:
  displayName: Weather Agent
  context: /weather
  specVersion: "1.0"
  signCard: true                                   # gateway re-signs; JWKS route auto-exposed
  upstream:
    url: http://weather:9001
    auth:
      type: bearer
      header: Authorization
      value: "{{ secret weather-backend-token }}"
  # Inline snapshot — the SOURCE fields only; the controller derives security + rewrites URLs + signs
  agentCard:
    name: Weather Agent
    description: Returns current weather for a supported city.
    supportedInterfaces:
      - protocolBinding: JSONRPC
        protocolVersion: "1.0"
        url: http://weather:9001/                  # upstream url; controller rewrites to gateway
      - protocolBinding: HTTP+JSON
        protocolVersion: "1.0"
        url: http://weather:9001/
    capabilities:
      streaming: true
    skills:
      - id: get_weather
        name: Get Weather
        description: Current weather for a supported city.
        tags: ["weather"]
  policies:
    - { name: jwt-auth,      version: v1, params: { issuers: ["https://idp.example.com"], requiredScopes: ["a2a.invoke"] } }
    - { name: a2a-ratelimit, version: v1, params: { limit: 100, unit: minute, key: consumer } }

Note the inline snapshot carries source fields only — no securitySchemes/securityRequirements (derived from the jwt-auth policy) and no signatures (the controller re-signs).

Snapshot & drift

• Snapshot only the source fields — name, description, skills, capabilities, supportedInterfaces. Not upstream securitySchemes/securityRequirements (derived from policies) and not upstream signatures (invalidated by the rewrite).
• The snapshot gives curation a stable base and makes preview == served a guarantee.
• Its cost is drift-by-design → pair it with a re-sync + diff action: re-fetch upstream → diff against snapshot → re-curate → re-deploy (also the visible "your card is out of date" affordance).
• Open question: manual re-sync ("check for updates") vs. periodic control-plane polling that flags drift automatically (freshness vs. load/complexity).

Card editing & devportal publishing (discovery)

Editing the card in AI Workspace is valuable beyond mediation: the controller-generated card is a baseline, and the workspace lets operators curate it — descriptions, tags, surfaced skills, public-vs-extended split, docs links. The curated card then has two destinations:

1. Gateway well-known route — machine discovery for calling agents/clients.
2. Devportal catalog — human/team discovery: browse available agents, read skills/docs, subscribe, obtain credentials.

This directly addresses the registry gap (A2A has no standardized registry yet, a2aproject/A2A#741) — the devportal becomes the discovery surface for governed A2A agents, exactly as it already is for REST/MCP/LLM APIs. Curation feeds both destinations from one edited card, published from the same versioned card revision to keep them consistent.

Proposal: acquire the card by snapshot-and-serve at deploy (not live proxy-and-rewrite — signing and curation both favor it); the controller computes the served card from the pushed spec (agentCardUrl/snapshot + policies + cardOverrides + signCard), serving it from a synth well-known route and signing once at deploy. AI Workspace adds authoring + preview + curation on top, and publishes the curated card to both the gateway and the devportal. Upstream-auth secret note: the backend credential is always manual in both modes — the card reveals only which scheme, never the secret.

Transports: JSON-RPC methods ↔ HTTP+JSON paths (v1.0)

Every A2A operation maps onto both bindings the gateway must support. In JSON-RPC everything hits POST / and the operation is selected by the method field; in HTTP+JSON the operation is the HTTP verb + path. These are the routes the gateway classifies, authenticates, and rate-limits.

Operation	JSON-RPC method (POST /)	HTTP+JSON / REST
Send message	SendMessage	POST /message:send
Send message (streaming)	SendStreamingMessage	POST /message:stream
Subscribe / resubscribe to task	SubscribeToTask	GET or POST /tasks/{id}:subscribe
Get task	GetTask	GET /tasks/{id}
List tasks	ListTasks	GET /tasks
Cancel task	CancelTask	POST /tasks/{id}:cancel
Get extended (authenticated) agent card	GetExtendedAgentCard	GET /extendedAgentCard
Discover the public agent card	(n/a — not an operation)	GET /.well-known/agent-card.json

(The push-notification / webhook config operations — CreateTaskPushNotificationConfig etc. / …/tasks/{id}/pushNotificationConfigs — are deferred along with the gateway-mediated webhook story and omitted here.)

How the two bindings differ (same operations, different envelope):

• JSON-RPC — all methods hit the single endpoint POST /; the operation is chosen by the method field (PascalCase), and params carries the request message. Responses are wrapped in the JSON-RPC envelope ({"jsonrpc","id","result"}), with result holding the typed payload (e.g. SendMessageResponse = {"task": …}).
• HTTP+JSON / REST — the operation is the HTTP verb + path; for POSTs the body is the bare request message (no JSON-RPC wrapper) and the response is the bare object. {id} is the task id.
• Streaming operations (SendStreamingMessage, SubscribeToTask) return text/event-stream (SSE) in both bindings; each frame is a StreamResponse envelope ({"statusUpdate": …} / {"artifactUpdate": …} / {"task": …}), wrapped in a JSON-RPC result for JSON-RPC, or emitted bare for REST.

Note: these are the v1.0 names. The older v0.2.x/0.3.x JSON-RPC binding used slash-style methods (message/send, tasks/get, tasks/cancel, …) — which is why gateways documented against 0.x list those instead. Since we scope to v1.x, the gateway classifies against the PascalCase set above (bucketing unrecognized methods as "unknown" to bound metric cardinality).

[ofekron]

Maintainer disclosure: I build Better Agent, a local agent control plane where durable identity, approvals, and restart recovery are backend-owned.

The proxy shape is strong, but I would add acceptance criteria at the task lifecycle boundary, not only the request boundary:

• Bind each created A2A task to caller identity, target agent, policy version, and delegated authority. Apply that binding to get/list/cancel/subscribe so a valid caller cannot enumerate or control another caller’s task.
• Define identity propagation for agent chains. The downstream needs both the immediate caller and original actor; a generic gateway credential should not erase who delegated the work.
• Re-authorize long-lived SSE subscriptions on reconnect and credential/policy changes. Initial authentication alone is insufficient for a stream that may outlive a token or revocation.
• Make JSON-RPC ↔ HTTP+JSON conversion preserve idempotency keys, cancellation, error classes, ordering, and backpressure. Retries at the proxy must not duplicate SendMessage side effects.
• Treat card verification and gateway re-signing as two provenance steps. The published signature should identify the gateway as mediator and retain evidence of which upstream card/version was verified; it must not imply the upstream signed the rewritten card.
• Redact credentials and sensitive message content from traces by default. Correlation IDs, actor/agent IDs, policy verdicts, and content hashes are usually enough for audit.

I would also rate-limit by estimated work/cost as well as request count: one streaming SendMessage can be more expensive than hundreds of task reads.

License note for the implementation reference: Better Agent is source-available and free for non-commercial use; commercial use requires separate permission.

[RakhithaRR]

Hi @ofekron,

Thanks for the suggestions! We have identified some of those as improvements we can make in later phases of the implementation.

Could you elaborate the work/cost based rate limiting you have suggested here? Is there a specific idea you have on how the cost should be assigned/calculated? Or a metric to define how much work is done?