NylorunDocsBeta
Runtime APISessionsA2A

Call an agent over A2A

POST
/v1/a2a/agents/{agentId}

A2A 1.0 JSON-RPC, for a subject, under the Nylorun profile v2 (Host feature a2a-profile-v2). SendMessage blocks up to the Runtime limit a2aWaitMs (5 minutes by default; then the task is answered still WORKING) unless returnImmediately; GetTask (with historyLength), CancelTask and ListTasks; and the four push notification config methods, plus configuration.taskPushNotificationConfig in SendMessage: each update is POSTed as one StreamResponse, signed with Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature with the Runtime's a2a.push.secret) and X-A2A-Notification-Token, at least once, retried for up to 24 hours, to hosts the Runtime allows (a2a.push.allowHosts for private ones). A message to a busy context is queued and answered with the task that will take it (TASK_STATE_SUBMITTED); message.metadata.delivery: "reject" asks for UnsupportedOperationError (reason CONTEXT_BUSY) instead, and "steer" (Host feature a2a-steer) steers it into the running turn, as a session message's delivery: "steer": the turn takes it before its next step and the task is that turn's; to an idle context, a workflow's, or a turn past its last step it is an ordinary message. The task answered to a steer carries metadata.delivery: steered, or queued when it started a turn or waits as a queued message. A queued task never waits for good (Host feature queue-recovery): when its Agent refuses its turn's start (a disk copy, a lost pod), the start is tried again until the Runtime limit queuedStartMs (15 minutes by default), and then, or at once for a refusal no retry changes, the task is TASK_STATE_FAILED with a status message saying why; CancelTask on a queued task takes it out of the queue, a task running in the context or not, and answers TASK_STATE_CANCELED. Both are pushed. message.metadata.removeTools (Host feature remove-tools) names the tools a new message's turn may not use, as a session message's removeTools. message.metadata.role (Host feature model-roles) opens a new context's session on that model role, as PUT /v1/sessions/{id}'s role; a role the Agent's version does not declare is InvalidParams. A message is text, one data part, or text with raw files (stored as artifacts of the context's session) and url files (fetched by the Runtime), each at most the Runtime limit inlineFileBytes (20 MiB by default). An approval, question or connection the task waits for (AUTH_REQUIRED or INPUT_REQUIRED) is shown under interactions/v1 and answered on the same task with { interactionId, approved } or { interactionId, value } under that URI in the message's metadata; text never approves. Artifacts carry the turn's output and the files it wrote, as url parts at /v1/a2a/files/… with files/v1; the task's metadata carries progress/v1, telemetry/v1 and effects/v1. Extension data is answered only for the extensions activated with A2A-Extensions. A context is one session per subject, agent and contextId; a task is one turn. JSON-RPC errors are answered with 200; limits, scopes and unavailable streams stay HTTP errors. Not served: streaming, GetExtendedAgentCard.

Authorization

headerAuthorizationBearer <token>

An application key of the Tenant (PUT /v1/tenant/keys/{keyId}), or Studio's key, derived from the admin key. With Nylorun-Subject and Nylorun-Scopes, it acts for that person, narrowed to those scopes. Never accepted from a browser (Origin).

Path Parameters

agentId*string

Query Parameters

A2A-Version?string

Or the A2A-Version header: 1.0

Header Parameters

Nylorun-Protocol*string

The protocol version, 18

Nylorun-Subject?string

The person an application key acts for

Nylorun-Scopes?string

The subject's space-separated scopes; required with a subject

traceparent?string

W3C trace context: the turn this request starts joins the caller's trace (feature traces). A malformed value is ignored

tracestate?string

W3C trace context, kept with traceparent

A2A-Extensions?string

Comma-separated profile v2 extension URIs to activate; the answer echoes the activated ones

Request Body

application/json
  1. body
jsonrpc*"2.0"
Value in"2.0"
id?string|number|null
method*string

SendMessage, GetTask, CancelTask, CreateTaskPushNotificationConfig, GetTaskPushNotificationConfig, ListTaskPushNotificationConfigs, DeleteTaskPushNotificationConfig or ListTasks; others answer their A2A error

params?unknown
[key: string]?unknown

Response Body

The JSON-RPC answer: a result, or an A2A error

application/json
  1. response
jsonrpc*"2.0"
Value in"2.0"
id*string|number|null
result?unknown
error?
[key: string]?unknown
curl -X POST "https://example.com/v1/a2a/agents/string" \  -H "Nylorun-Protocol: string" \  -H "Content-Type: application/json" \  -d '{    "jsonrpc": "2.0",    "method": "string",    "property1": null,    "property2": null  }'
{  "jsonrpc": "2.0",  "id": "string",  "result": null,  "error": {    "code": 0,    "message": "string",    "data": null  },  "property1": null,  "property2": null}