A2A agents

Operations guide: configure, deploy and observe the gateway. What the capability does, product side: product guide; calling it: developer guide.

Goal: put the traffic between agents (A2A v1.0) through the gateway - under a quota, an audit and a verified identity - without the gateway terminating the protocol. Available since 1.2.0; verifying upstream cards, the re-signed published card, agent-to-agent delegation and the registry are planned for 1.9.0.

What the gateway does, and does not. It routes, authenticates, holds the tenant, counts, guards push targets, relays without buffering and audits without content. It keeps no task and delivers no webhook: the upstream agent binds each task to the identity it receives - a requirement for the agent's team (another caller must get "task not found").

Declare an agent. Its v1.0 agent card is a contract versioned in Git, listed in contracts.a2a; its supportedInterfaces carry the gateway's addresses (JSONRPC, HTTP+JSON - gRPC refused); x-flexway-a2a says what is Flexway's and is not published. The upstream is protocol: a2a and declares token_exchange - refused at load otherwise. Each security scheme of the card must match a configured mechanism (openIdConnectSecurityScheme -> the discovery of an issuer of auth.issuers). Until upstream card verification ships (planned for 1.9.0), verify: none is required: the upstream's card is not verified, and the diff says so. Full example: A2A agent behind the gateway.

Quotas and streams. Writing costs (write), reading a task is free (free: no bucket, no tenant quota); x-flexway-a2a.methods changes a method's class. SendStreamingMessage and SubscribeToTask take a place of max_streams (per caller and per replica) and last at most max_task_duration - past it, the stream ends; a longer task is followed with GetTask.

Push notifications. Closed by default: without agents.a2a.push.allowed_hosts, none. With it: https only, a listed name (or under a *.domain), never an address in any form. The gateway does not resolve the name: a permitted name later pointing inside is for the delivering agent to watch.

The published card. GET <path of the first interface>/.well-known/agent-card.json: the declared card without x-flexway-a2a, anonymous, with an ETag. Give this URL to calling agents. Unsigned until 1.9.0. The extended card is relayed, at the gateway's addresses, never cached.

Check.

• the published card answers, without x-flexway-a2a;
• a JSON-RPC SendMessage then an HTTP+JSON GetTask answer, with A2A-Version: 1.0;
• the upstream agent receives a token of its audience, never the caller's;
• /config (admin) shows a2a.agents: bindings, methods and classes;
• flexway_a2a_calls_total counts by agent, method, binding and outcome.