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 path | What 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.json | One 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
/a2a/v1/agents/{name}JSON-RPC 2.0. Send the header A2A-Version: 1.0, or ?A2A-Version=1.0.
Methods
SendMessagemethodoptionalTASK_STATE_WORKING if it is still going when the wait ends. With returnImmediately, answers at once with the task WORKING.SendStreamingMessagemethodoptionalGetTaskmethodoptionalhistoryLength honoured.ListTasksmethodoptionalcontextId and state; pageSize up to 100.CancelTaskmethodoptionalA 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
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 path | Who | What it does |
|---|---|---|
GET /projects/{project_id}/agent-policies/{agent_name}/a2a-callers | viewer | The 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-callers | project admin | Set it. An empty list allows none. |
Agent keys
These routes take a Keycloak access token.
| Method and path | Who | What it does |
|---|---|---|
POST /projects/{project_id}/agent-keys | project admin | Body: 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-keys | developer or admin | Keys, 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 admin | Revoke a key. Takes effect on the next call. |
POST /projects/{project_id}/agent-keys/{key_id}/rotate | project admin | New secret, same key. Body: overlap_hours. |
GET /projects/{project_id}/agent-policies | developer or admin | Every agent of the project with a policy or a key. |