Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

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

Aperta
  • Qualcosa non va?
#538 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
45/100
Tipo di issue
Documentazione
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
grpc
Ambito
api, documentation

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

help wanted

[!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.

Operation Path
Read the Agent Card GET /agents/{namespace}/{name}/.well-known/agent-card.json
Call JSON-RPC, including streaming POST /agents/{namespace}/{name}

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.
Lingua principale
TypeScript
Stelle
20
Fork
66
Merge medio
15h 35m
PR unite (30g)
59

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di kagent-dev/website

Tutte le issue di kagent-dev/website

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.