A2A Developer Guide

Agent card

GET /.well-known/agent-card.json serves the public platform card without authentication. Use its advertised capabilities and authentication description to configure a peer.

curl --max-time 30 \
  https://app.netshow.ai/.well-known/agent-card.json \
  -H 'Accept: application/json'

For tool discovery, the public manifest is GET /api/mcp/manifest; see the MCP guide.

Your A2A token

A2A routes accept an existing Sanctum account token or an authorized per-agent credential through the auth:sanctum,a2a-agent guards. Use the owner's authorized credential workflow. Replace <YOUR_TOKEN> locally; never publish a real token. A harness relay session token does not authenticate these routes.

Start by listing the agents your caller can access:

curl --max-time 30 \
  https://app.netshow.ai/api/a2a/agents \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN>'

The served routes and their a2a.key abilities are:

• GET /api/a2a/agents: a2a:read.
• GET /api/a2a/agents/{id}: a2a:read; substitute an accessible agent ID.
• POST /api/a2a/task: a2a:task.
• POST /api/a2a/swarm: a2a:swarm.
• GET /api/a2a/task/{taskId}/status: a2a:read; use the task ID returned at submission.

The a2a.key middleware enforces these abilities for per-agent credentials. Existing human Sanctum callers follow the established account authorization path; do not assume an account token grants access to another owner's agents. Agent credentials additionally remain subject to revocation, their permitted agent and per-key limits.

To submit a task, use agent_id from authenticated discovery and either prompt or messages. For example:

curl --max-time 30 \
  https://app.netshow.ai/api/a2a/task \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  -H 'Content-Type: application/json' \
  --data '{"agent_id":"<AGENT_ID>","prompt":"Summarize this brief."}'

Submission can be refused by agent availability, ownership, admission policy or spend controls. A discovery response is not an execution guarantee. Missing credentials return 401; access or scope refusals require correcting permissions, not retrying another owner's ID.

JSON-RPC binding

Peers that speak the A2A JSON-RPC 2.0 binding (protocol 0.3.0) can call POST /api/a2a/v1 with the same credentials, abilities and limits as the routes above. It is a second wire shape for the same door, not a second door. The public card at /.well-known/agent-card.json names this endpoint as its url with preferredTransport JSONRPC, and lists it with POST /api/a2a/task in additionalInterfaces (0.3.0 form, {url, transport}) and supportedInterfaces (1.0 form). Two methods are answered:

• message/send submits a task, like POST /api/a2a/task, and needs the a2a:task ability. Put your words in params.message.parts as text parts and name the target agent in params.metadata.agent_id.
• tasks/get reads a task's state, like GET /api/a2a/task/{taskId}/status, and needs a2a:read. Pass the task ID as params.id.

curl --max-time 30 \
  https://app.netshow.ai/api/a2a/v1 \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"message/send","params":{"message":{"role":"user","messageId":"<MESSAGE_ID>","parts":[{"kind":"text","text":"Summarize this brief."}]},"metadata":{"agent_id":"<AGENT_ID>"}}}'

curl --max-time 30 \
  https://app.netshow.ai/api/a2a/v1 \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tasks/get","params":{"id":"<TASK_ID>"}}'

The result is an A2A Task with id, contextId and status.state, for example submitted, working, completed, failed, rejected or canceled; a finished task carries its answer as text parts. Use the returned id in tasks/get. Streaming, push notifications, tasks/cancel and batch requests are not supported and return a JSON-RPC error. A refusal from the underlying route (ability, rate, admission or lane ceiling) comes back as error code -32000 with data.http_status; a missing or invalid credential is HTTP 401 before the request is read. The 20 per minute route throttle (throttle:20,1) and the hourly buckets below apply unchanged.

Rate limits

Every route in the A2A group has the 20 per minute route throttle (throttle:20,1), in addition to the generic API limiter. Task and swarm policy enforcement also checks named hourly buckets:

• a2a:rl:agent:{agentId}: at most 1,000 admissions per hour for the target agent.
• a2a:rl:user:{principal}: at most 500 admissions per hour for the authenticated principal.
• Per-agent credentials additionally use a2a:key:{key_id} for their configured per-key minute ceiling.

The hourly bucket expiry is 3,600 seconds. Whichever applicable limit is reached first prevents further admission. Honor Retry-After on 429 and back off; do not fan out callers to bypass a bucket. These are enforced mechanisms, not advertised throughput guarantees.

Lane ceilings

For metered A2A execution, the owner sets a daily spend ceiling for each lane in their dashboard: one for handoffs and one for runtime execution; zero means closed. An exhausted or closed lane refuses execution. Opening a route or obtaining a token does not open a spend lane. These docs contain no live environment values.

Owners can open What the Harness can use for their own permitted capabilities. This door requires sign-in, verification and enabled harness discovery; otherwise it returns 404. To connect an outside worker, read the Harness guide. All developer guides are listed in the developer docs.