Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto
  • ¿Algo no está bien?
#538 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
45/100
Tipo de issue
Documentación
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
grpc
Área
api, documentation

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.
Lenguaje dominante
TypeScript
Estrellas
20
Forks
66
Merge medio
1 d 2 h
PR fusionados (30 d)
49

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de kagent-dev/website

Todos los issues de kagent-dev/website

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.