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: where the rewrite executes, and card curation for discovery

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, optionally re-signed with the gateway key + published JWKS. Two questions: where the rewrite runs, and who can curate the result.

Card mediation is a system policy. The gateway applies it automatically to every kind: A2a proxy — fetching/rewriting 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.

Runtime serving is settled

However the card is produced, the gateway serves it from a local, non-forwarding route at /{context}/.well-known/agent-card.json — the same pattern used to synthesize MCP's OAuth Protected Resource Metadata. The gateway never proxies the well-known path upstream at request time (available even if upstream is down, consistent across replicas). Unlike the MCP tool list (proxied live + policy-filtered), a signed discovery card is curated config, so the synth pattern fits.

Where the rewrite executes

Option A — control-plane only. platform-api rewrites and bakes the finished card into the deployed config; the gateway just serves it. Problem: gateway-only users must hand-author the whole agentCard block.

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 }}"
  # Full rewritten card must be authored by hand (no controller mediation)
  agentCard:
    name: Weather Agent
    description: Returns current weather for a supported city.
    supportedInterfaces:
      - protocolBinding: JSONRPC
        protocolVersion: "1.0"
        url: https://gw.example.com/weather        # rewritten to gateway, by hand
      - protocolBinding: HTTP+JSON
        protocolVersion: "1.0"
        url: https://gw.example.com/weather
    capabilities:
      streaming: true
    securitySchemes:                               # must mirror the jwt-auth policy, by hand
      oauth2:
        oauth2:
          flows:
            clientCredentials:
              tokenUrl: https://idp.example.com/oauth2/token
              scopes:
                a2a.invoke: Invoke the weather agent
    securityRequirements:
      - oauth2: ["a2a.invoke"]
    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 } }

Option B — gateway-controller, deploy-time (recommended). fetch + validate + rewrite in the controller transformer, once at deploy/reconcile. The user supplies only agentCardUrl; the controller produces the served card. Works for both modes; AI Workspace layers editing on top of the same logic. Trade-off: one-time upstream fetch at deploy (retry / degraded status); an explicit spec.agentCard override remains available for air-gapped deployments.

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 } }

The controller derives everything the Option-A card spells out by hand — the rewritten supportedInterfaces[].url (from context + gateway host), and securitySchemes/securityRequirements (from the jwt-auth policy). No agentCard block needed in the common case.

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 noted above (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.

Consequences to design for

1. Drift / re-sync. Card is produced at deploy time, so an upstream change leaves a stale served card — the control plane needs a re-sync (re-fetch → re-mediate → re-publish to gateway and devportal).
2. Upstream-auth secret is always manual — in both modes; the card reveals only which scheme, never the secret.

Proposal: card mediation = a deploy-time controller transform keyed off agentCardUrl (with inline spec.agentCard override), producing a baseline card served from a synth well-known route. AI Workspace adds a curation/editing layer on that card, and the curated result is published to both the gateway and the devportal — making the devportal the discovery catalog for A2A agents in the absence of a protocol-standard registry.

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).