Docs: cover the A2A HTTP and JSON-RPC transport for kagent 1.x

Read docs/architecture/a2a-transports.md and substrate-runtime/identity.md, then run examples/a2a-agents.md as written. Fetch an Agent Card, exercise JSON-RPC streaming and share-token permissions, and verify ingress behavior against a live instance. Done means the guide documents both transports, routing and naming changes, ingress requirements, and a resolved exposure policy.

[!IMPORTANT]
Rewritten for 1.0.0-alpha5 on 2026-09-29. This issue was filed against alpha4 and described a per-AgentInstance endpoint. alpha5 changed the URL shape, the resource it addresses, and the gRPC routing field. The original scoping is superseded; what follows is verified against the v1.0.0-alpha5 tag. Part of #549.

examples/a2a-agents.md uses grpcurl throughout and documents no HTTP path. kagent serves A2A over HTTP/JSON-RPC alongside gRPC, with a discoverable Agent Card, and a reader who wants an ordinary HTTP client has nothing to follow.

Upstream's docs/architecture/a2a-transports.md is the endpoint contract and the right source. It is an architecture document rather than a task guide.

The endpoint surface

Both transports are served on the controller's API listener, port 8083 by default, and share the same Session authorization, durable tasks, history, and runtime lifecycle.

The URL addresses an Agent, not an AgentInstance. This is the alpha5 change: alpha4 served /agents/{instance-id}, and the resource that a conversation belongs to is now a Session.

• HTTP requests need no tenant. gRPC requests use the standard A2A tenant field as namespace/name, advertised only on the card's gRPC interface. An HTTP request that does supply a tenant must have it match the URL.
• Session.id is the message contextId. Omitting both context and task IDs creates a new conversation; retrying that first message with the same message ID reuses it. A task-only request resolves the conversation from the globally unique task ID.
• There is no deployment-wide Agent Card, because the gateway serves many agents.

JSON-RPC uses the pinned upstream A2A v1 SDK: SendMessage, SendStreamingMessage, GetTask, ListTasks, CancelTask, SubscribeToTask, and GetExtendedAgentCard. Those are the v1 names for what older clients called message/send, message/stream, tasks/get, tasks/list, tasks/cancel, and tasks/resubscribe, which is worth stating for anyone arriving with a pre-v1 client.

Behavior the API does not announce

• controller.a2aGatewayUrl changed meaning in alpha4 and still holds. It was the public gRPC URL advertised by Agent Cards; it is now the gateway base URL for both transports, and HTTP interfaces append the agent path to it, preserving any deployment prefix. Its default is the controller's cluster Service URL.
• An ingress with a prefix must strip it before forwarding to the core listener, and must forward streaming responses without buffering. Neither is enforced by a chart value.
• The card advertises JSON-RPC first, then gRPC. It comes from the Agent's latest successful revision, or from a shared session's pinned revision, and retains runtime extensions while reporting the gateway's streaming capabilities.
• Share tokens grade by permission. A validated X-Share-Token supplements the authenticated user's access to its session: a read-only share permits card and task reads and subscriptions, and a read-write share also permits messages and cancellation. Cards are not publicly cached.

The conflict to resolve before writing

substrate-runtime/identity.md warns against exposing port 8083 outside the cluster, because the open source build's authenticator admits every request. The HTTP transport is served on that same listener, and the architecture document describes setting a2aGatewayUrl and putting an ingress in front precisely so agents can be reached from outside.

alpha5 changes this picture and it must be re-checked before writing. kagent#2971 restored controller.auth.mode and controller.auth.userIdClaim, so the permissive posture is no longer the only option. Establish what the authenticated configuration actually allows, then say which argument won. This is the main open question in this issue.

What to check before starting

1. Read docs/architecture/a2a-transports.md at the release being documented.
2. Run the existing examples/a2a-agents.md guide as written, so the gRPC path is known to work before an HTTP path joins it. Note that the page is written around AgentInstance and needs the Session rename from #549 regardless.
3. Fetch a card over HTTP and confirm the interface ordering and retained extensions.
4. Exercise streaming over JSON-RPC, and confirm what a client sees when an ingress buffers.
5. Confirm the share-token grading through both transports rather than inferring it.

Done when

• Both endpoint paths are documented in their alpha5 form, with a working curl example for the card and for a JSON-RPC call.
• The page states that the URL addresses an Agent, and that Session.id is the contextId.
• The v1 method names are listed against their pre-v1 equivalents.
• The a2aGatewayUrl meaning is covered wherever that value is documented.
• The ingress requirements, prefix stripping and unbuffered streaming, are stated.
• The exposure question against identity.md is resolved against alpha5 authentication rather than left for the reader.
• Every command was run against a live Agent.