Call an agent over A2A
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.
AuthorizationBearer <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).
agentId*stringA2A-Version?stringOr the A2A-Version header: 1.0
Nylorun-Protocol*stringThe protocol version, 18
Nylorun-Subject?stringThe person an application key acts for
Nylorun-Scopes?stringThe subject's space-separated scopes; required with a subject
traceparent?stringW3C trace context: the turn this request starts joins the caller's trace (feature traces). A malformed value is ignored
tracestate?stringW3C trace context, kept with traceparent
A2A-Extensions?stringComma-separated profile v2 extension URIs to activate; the answer echoes the activated ones
application/json- body
jsonrpc*"2.0""2.0"id?string|number|nullmethod*stringSendMessage, GetTask, CancelTask, CreateTaskPushNotificationConfig, GetTaskPushNotificationConfig, ListTaskPushNotificationConfigs, DeleteTaskPushNotificationConfig or ListTasks; others answer their A2A error
params?unknown[key: string]?unknownThe JSON-RPC answer: a result, or an A2A error
application/json- response
jsonrpc*"2.0""2.0"id*string|number|nullresult?unknownerror?[key: string]?unknowncurl -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}Get an agent's A2A card GET
Previous Page
Download a file an A2A task wrote GET
Where the `url` parts of an A2A task's file artifacts point (Host feature `a2a-profile-v2`, `files/v1`): a file version's bytes, with Range, or a folder version as a zip. Served only to the subject whose session wrote it, as the A2A endpoint is: send the same credential, `Nylorun-Subject` and `Nylorun-Scopes`. Another subject's artifact is a `404`.