A2A API Reference
Detailed specification of the A2A (Agent-to-Agent Protocol) endpoints provided by the AGENTIC STAR Marketplace edition. External agents and applications that support A2A call registered Agents and published workflows (projects). Both A2A 0.3 and 1.0 are supported.
A2A is available only in environments where an administrator has opened the inbound endpoints (MCP and A2A) and set the standard token endpoint. Otherwise the endpoints return 404 Not Found. For how to open them, see the Helm Values Reference in the Build section.
Base URL
All requests are sent to the following base URL. Replace <your-domain> with the domain of your environment.
https://<your-domain>Endpoints
Each registered Agent and each published workflow has its own endpoint and Agent Card. There is no endpoint that lists them.
| Method | Endpoint | Description |
|---|---|---|
POST | /api/v1/a2a/agents/{agentId}/ | A2A JSON-RPC endpoint of a registered Agent |
GET | /api/v1/a2a/agents/{agentId}/.well-known/agent-card.json | Its Agent Card |
POST | /api/v1/a2a/projects/{projectId}/ | A2A JSON-RPC endpoint of a published workflow |
GET | /api/v1/a2a/projects/{projectId}/.well-known/agent-card.json | Its Agent Card |
- As in the Agent Card's
urlandsupportedInterfaces, the endpoint URL ends with/(it works without it as well) - Getting an Agent Card also requires a token. The token rules are the same as in "Authentication" below
agentIdis the ID of an Agent the administrator registered in the admin console. Check it with your administratorprojectIdis the ID of a workflow the project owner published over A2A. Check it with the owner. Only workflows whose publishing settings have the name and description of the A2A card can be called
Protocol: JSON-RPC 2.0 (blocking sends use application/json; streaming uses SSE)
Agent Card
There are two forms of the Agent Card. With the request header A2A-Version: 1.0, you get an Agent Card in the 1.0 form only; without the header, or with any other value, you get a single Agent Card that carries the fields of both 0.3 and 1.0.
| Item | Registered Agent | Published workflow |
|---|---|---|
| Name and description | The name and description of the A2A card written in the admin console; if not written, the Agent's display name and description | The name and description of the A2A card written in the project's publishing settings |
| Skills | The skills of the A2A card; if not written, one skill from the name and description | The skills of the A2A card; if not written, one skill from the name and description |
| Streaming | Supported (streaming: true) | Not supported (streaming: false) |
| Input and output modes | As set on the A2A card; text/plain if not set | Input text/plain and application/json, output text/plain |
Authentication
All requests (including getting an Agent Card) must include the Authorization: Bearer <access_token> header. The following two kinds of tokens can be used. The Marketplace edition applies no scope restrictions.
| Token | How to get it | Where it appears in the Agent Card |
|---|---|---|
| A system integration (service account) token | Client Credentials flow of the standard token endpoint (https://<auth-domain>/api/v1/oauth/token) (Authentication API Reference) | tokenUrl of oauth2ClientCredentials |
| A user token of an application (sign-in from an external tool) | Authorization Code flow (Authentication Guide) | oauth2AuthorizationCode, only in environments where the entrance for sign-in from an external tool is open |
- Sign-in from an external tool is available only in environments where an administrator has opened its entrance (API Setup Guide)
- A user token obtained in any other way (such as the token used when signing in to the Main Screen) gets
404 Not Found - A missing or invalid token gets
401 Unauthorized
Versions and Methods
The request header A2A-Version decides the version (not sent or 0.3 is 0.3, 1.0 is 1.0, anything else is -32009). Method names and the shape of streaming events follow the A2A specification and are the same as in the SaaS edition. The task shape is the same as in the SaaS edition for the registered Agent endpoint; for the published workflow endpoint, a task is one run (see the sections below). See "Versions", "JSON-RPC Methods", and "Task Shape" in the A2A API Reference (SaaS edition).
Registered Agent Endpoint
POST /api/v1/a2a/agents/{agentId}/ sends a task to that registered Agent. Versions, methods, task shape, where a message goes, listing, canceling, and resubscribing are the same as A2A in the SaaS edition, with the following differences.
| Item | Marketplace edition |
|---|---|
| Available methods | Send, streaming, get, cancel, and resubscribe (0.3 and 1.0), and list (ListTasks on 1.0) |
| Task shape | The whole conversation on 0.3, one request on 1.0 (same as the SaaS edition) |
| Task ID on 1.0 | An ID per registered Agent. Sending it to another Agent's endpoint returns -32001 (Task Not Found) |
metadata of a message | agentMode, agentLevel, reportMode, and personaKey are not used (sending them has no effect) |
| Attached files | Content parts (base64) only; URL parts are not supported |
| Answering a question | The same contextId on 0.3, the same taskId on 1.0 (same as the SaaS edition) |
Where a message goes (the combination of taskId and contextId), listing, canceling, and resubscribing work the same as in the SaaS edition.
Published Workflow Endpoint
POST /api/v1/a2a/projects/{projectId}/ runs the published workflow once (a run). One message starts one run, and a task is a run.
Who can call it
- A system integration (service account) token
- Among users who signed in from an external tool, the owners of that project. A member who is not an owner is rejected with
owner_only, and someone who is not a member withproject_not_found
Input
| Message parts | Input to the run |
|---|---|
| Text parts (one or more) | A string joining them with line breaks |
| Exactly one data part (whose content is a JSON object) | That object |
| Text and data mixed, two or more data parts, or data that is not an object | -32602 (INVALID_INPUT) |
| File parts | -32005 (files are not supported) |
The input must be 8,000 characters or less as JSON and 16 KB or less in UTF-8 (about 5,000 Japanese characters). Beyond that, the response is -32602 (PAYLOAD_TOO_LARGE).
Sending
| Setting | Response |
|---|---|
configuration.returnImmediately: true on 1.0, or configuration.blocking absent or false on 0.3 | Returns the task of the started run (submitted on 0.3, TASK_STATE_SUBMITTED on 1.0) right away |
| Otherwise (waiting) | Waits until the run finishes and returns the task in its final state. By default it waits at most 2 hours; beyond that the response is -32603 (EXECUTION_TIMEOUT). The run keeps going, so follow it with get (GetTask / tasks/get). Sending it again as a new message starts another run |
- When the same caller sends again with the same
messageIdand the same input, no new run starts and the earlier run is returned. With the samemessageIdand different input, the send is rejected - A send with
taskIdis rejected (each message starts a new run). If that run exists the response is-32004, otherwise-32001 contextIdis always theprojectId. Sending another value returns-32602(CONTEXT_NOT_FOUND)
Task states
| Run state | 0.3 | 1.0 |
|---|---|---|
| Running | working | TASK_STATE_WORKING |
| Waiting for review (a review request a person decides in the AGENTIC STAR screen) | working | TASK_STATE_WORKING |
| Completed | completed | TASK_STATE_COMPLETED |
| Failed | failed | TASK_STATE_FAILED |
| Rejected | rejected | TASK_STATE_REJECTED |
| Canceled | canceled | TASK_STATE_CANCELED |
status.message holds the run's summary (if there is none, the output summary of the step that finished last; if neither exists, it is absent). Artifacts (artifacts) and history (history) are not returned.
Getting and listing
params.idof get (tasks/get/GetTask) is the task ID (the run ID) returned when you sent the message- List (
ListTaskson 1.0) returns the runs that the caller started in that project. You can filter by state (status) and time (statusTimestampAfter), the page size (pageSize) is 1 to 100 (default 50), andpageTokenreads the next page. The state may lag behind get by up to about 1 minute
What is not supported
| Operation | Response |
|---|---|
Cancel (tasks/cancel / CancelTask) | -32004 |
Streaming (message/stream / SendStreamingMessage) and resubscribing (tasks/resubscribe / SubscribeToTask) | -32004 (no run is started) |
| Push notification configuration | -32003 |
Errors
The error codes are the same as in the SaaS edition (A2A API Reference (SaaS edition) — Error Codes). Scopes are not checked, so MISSING_SCOPE is not returned, and personaKey is not used, so INVALID_PERSONA_KEY is not returned either. The ones specific to the Marketplace edition are below. The detail code is in error.data.code on 0.3 and in error.data[].metadata.code on 1.0.
| Case | Endpoint (POST) | Agent Card (GET) |
|---|---|---|
| The registered Agent does not exist or is disabled | -32602 (agent_not_found) | 404 (agent_not_found) |
| The workflow is not published or does not exist, or the caller is not a member | -32602 (project_not_found) | 404 (project_not_found) |
| A member who is not an owner | -32600 (owner_only) | 403 (owner_only) |
| The input to a published workflow is not in an accepted form | -32602 (INVALID_INPUT) | — |
| The input to a published workflow is too long | -32602 (PAYLOAD_TOO_LARGE) | — |
| The list of registered Agents has never been read, or the list of published workflows cannot be read | -32603 (with guidance to wait and retry) | 503 |
A project that is not published, does not exist, or is a cycle all return the same project_not_found, without telling which. Agent Card errors use the same error format as the REST API.
See Also
- A2A API Reference (SaaS edition) — Details of methods, task shape, and errors
- Authentication API Reference — The standard token endpoint
- API Setup Guide — Preparing service accounts and sign-in from an external tool
- A2A Specification — Full protocol details