Skip to main content

A2A and agent keys

The A2A routes let one agent call another of the same project over the Agent2Agent protocol, version 1.0, JSON-RPC binding. They take an agent key (vcag_). They are part of the code agents feature, and answer 404 while it is off. See Agents calling agents.

Discover agents​

Method and pathWhat it returns
GET /a2a/v1/agents{"agents": [AgentCard]}: the live agents of the caller's project that the caller may call.
GET /a2a/v1/agents/{name}/.well-known/agent-card.jsonOne agent's card. 404 when it isn't a callable agent of the project, 403 when the caller may not call it.

An agent card names the agent, its description, its live version, its endpoint, and the security scheme: a bearer agent key. Capabilities: streaming yes, push notifications no.

Send a message​

POST/a2a/v1/agents/{name}

JSON-RPC 2.0. Send the header A2A-Version: 1.0, or ?A2A-Version=1.0.

Methods​

SendMessagemethodoptional
Text parts are joined; data parts are sent as JSON. Blocking by default: answers with the task in its final state, or TASK_STATE_WORKING if it is still going when the wait ends. With returnImmediately, answers at once with the task WORKING.
SendStreamingMessagemethodoptional
Server-sent events: the task, status updates, the answer as artifact updates, then the final status.
GetTaskmethodoptional
One of the caller's tasks with this agent, with historyLength honoured.
ListTasksmethodoptional
The caller's tasks with this agent, newest first. Filters contextId and state; pageSize up to 100.
CancelTaskmethodoptional
Cancel a task that is still working.

A task's contextId is a thread with the agent: send it again to continue the conversation. metadata.vois carries the run_id, the agent_version and, while a person must decide, status: "awaiting_approval" and pending_approvals.

Responses​

200
A JSON-RPC result, or a JSON-RPC error such as task not found or unsupported operation.
401
No agent key, or it is revoked or expired.
403
Refused by a check. The JSON-RPC error's data.reason is caller_not_allowed, caller_tool_restricted, policy_denied, call_depth, usage_limited or key_scope.

Who may call an agent​

Method and pathWhoWhat it does
GET /projects/{project_id}/agent-policies/{agent_name}/a2a-callersviewerThe agents that may call this one: null for every agent of the project, or a list.
PUT /projects/{project_id}/agent-policies/{agent_name}/a2a-callersproject adminSet it. An empty list allows none.

Agent keys​

These routes take a Keycloak access token.

Method and pathWhoWhat it does
POST /projects/{project_id}/agent-keysproject adminBody: agent_name, name, optional expires_at. Returns the vcag_ key once, with the Model Gateway address to point a framework at.
GET /projects/{project_id}/agent-keysdeveloper or adminKeys, without secrets. Keys that Orchestrate manages for a code agent's deployment are marked and can't be revoked by hand.
DELETE /projects/{project_id}/agent-keys/{key_id}developer or adminRevoke a key. Takes effect on the next call.
POST /projects/{project_id}/agent-keys/{key_id}/rotateproject adminNew secret, same key. Body: overlap_hours.
GET /projects/{project_id}/agent-policiesdeveloper or adminEvery agent of the project with a policy or a key.
Was this page helpful?
On this page
Talk to our teamQuestions about licensing or sizing VoisX Orchestrate for your site? We can help.Talk to sales →