A2A API Reference
Detailed specification of the A2A (Agent-to-Agent Protocol) endpoint provided by the AGENTIC STAR SaaS edition. A2A is a JSON-RPC 2.0 interface used for agent-to-agent collaboration and task execution from a custom frontend. Both A2A 0.3 and 1.0 are supported.
This page covers A2A in the SaaS edition. For A2A in the Marketplace edition, see the A2A API Reference (Marketplace edition).
For a connection-method overview (including an Agent Card example), see the Connection Methods Guide.
Base URL
All requests are sent to the following base URL.
https://api.fd.agenticstar.tm.softbank.jpEndpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /.well-known/agent-card.json | Agent Card (skill list, auth scheme, capabilities). No token is required |
| POST | /api/v1/a2a | A2A JSON-RPC endpoint (0.3 and 1.0 methods) |
Protocol: JSON-RPC 2.0 (blocking sends use application/json; streaming uses SSE). The gRPC and HTTP+JSON bindings are not offered.
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. Both list the same /api/v1/a2a as the interface for 1.0 and for 0.3 (supportedInterfaces).
The skill descriptions in the Agent Card are short summaries. The details are on this page, and the Agent Card's documentationUrl points to this page.
Versions
The request header A2A-Version decides which version of A2A is spoken.
A2A-Version | Version |
|---|---|
| Not sent | 0.3 |
0.3 | 0.3 |
1.0 | 1.0 |
Anything else (2.0, 0.3.0, etc.) | Rejected with -32009 (version not supported) |
- Task IDs cannot be shared between versions. Sending a 0.3 task ID on 1.0 returns
-32001(Task Not Found), with guidance to continue bycontextIdinstead
Authentication
All requests must include the Authorization: Bearer <access_token> header (except getting the Agent Card). The token needs the a2a:all or a2a:connect scope.
| Scope | What it allows |
|---|---|
a2a:all | Every A2A operation (including file attachments and listing) |
a2a:connect | Connecting to the A2A endpoint. Each operation also needs the scope in the table below |
With a2a:connect, each operation needs the following scope (the same scope as the same operation in REST).
| Operation | Required scope |
|---|---|
Send (message/send, message/stream, SendMessage, SendStreamingMessage), get (tasks/get, GetTask), cancel (tasks/cancel, CancelTask), resubscribe (tasks/resubscribe, SubscribeToTask) | chat:exec |
| Send with files attached | chat:exec and chat:file |
List (ListTasks) | chat:history |
When a scope is missing, the response is -32600 (detail code MISSING_SCOPE) with the scopes needed and what to do next. For a new app, we recommend a2a:connect together with the scopes of the features you use.
The A2A scopes can be chosen for applications (Authorization Code flow). They cannot be chosen for system integrations (Client Credentials flow).
For token acquisition, see the Authentication API Reference (SaaS).
JSON-RPC Methods
| 0.3 | 1.0 | Style | Description |
|---|---|---|---|
message/send | SendMessage | Blocking (JSON) | Send a message and wait until it finishes or waits for input, then return the result |
message/stream | SendStreamingMessage | Streaming (SSE) | Send a message and receive events incrementally over SSE |
tasks/get | GetTask | Blocking (JSON) | Get the state of a task |
| — | ListTasks | Blocking (JSON) | List the tasks of one conversation (1.0 only) |
tasks/cancel | CancelTask | Blocking (JSON) | Cancel a task |
tasks/resubscribe | SubscribeToTask | Streaming (SSE) | Reconnect to the same task's stream after a disconnect |
The push notification configuration methods are not supported (-32003).
- Blocking sends (
message/sendandSendMessage) wait until the run finishes or waits for an answer. On 0.3,message/sendalways waits, regardless of the value ofconfiguration.blocking - With
configuration.returnImmediatelyset totrueonSendMessage(1.0), the task is returned right away as accepted (TASK_STATE_SUBMITTED). Follow it withGetTaskorSubscribeToTask
Task Shape
What a task covers differs by version.
| 0.3 | 1.0 | |
|---|---|---|
| One task | The whole conversation | One request (one user message and the response to it; continuing after answering a question stays in the same task) |
| Task ID | The conversation ID (same as contextId) | An ID per request |
contextId | The conversation ID | The conversation ID |
Treat task IDs and contextId as opaque values (their format may change without notice).
- The state names follow the specification. This endpoint does not return
rejected(TASK_STATE_REJECTED) - When waiting for an answer (
input-required/TASK_STATE_INPUT_REQUIRED),status.messageis the question, andmetadata.interactionTypeis one ofchoice,confirmation, andquestion. The ID of the question is inmetadata.interactionId(it may be absent) - On 0.3, the
artifactsoftasks/getandmessage/sendalso include those of earlier turns (because a task is the whole conversation). On 1.0, theartifactsandhistoryofGetTaskcover that request only - For get (
tasks/getandGetTask) and list (ListTasks),historyholds the most recent 100 messages whenhistoryLengthis not sent. The task in a send response holds only the message you sent inhistory. In both cases,historyLengthset to0returns nohistory
Where a Message Goes
On 0.3, the target conversation is decided by taskId, then metadata.conversationId, then contextId. With none of them, a new conversation starts.
On 1.0, it is decided by the combination of taskId and contextId. metadata.conversationId is not read.
taskId | contextId | Target request (without taskId, the latest request of the conversation) | Result |
|---|---|---|---|
| Present | Absent, or same as the conversation | Waiting for input | Continues (same task) |
| Present | Absent, or same as the conversation | In progress | -32600 (CONVERSATION_BUSY) |
| Present | Absent, or same as the conversation | Finished | -32004 (a finished task takes no more messages; guidance to send a new request with contextId) |
| Present | Different from the conversation | — | -32602 (CONTEXT_TASK_MISMATCH) |
| Unknown or malformed | — | — | -32001 (Task Not Found) |
| Absent | Present (your conversation) | Waiting for input | -32004 (guidance to answer with taskId) |
| Absent | Present (your conversation) | In progress | -32600 (CONVERSATION_BUSY) |
| Absent | Present (your conversation) | Finished, or no request yet | A new request in the same conversation (an archived conversation cannot be sent to; omit contextId to start a new conversation) |
| Absent | Unknown, or not your conversation | — | -32602 (CONTEXT_NOT_FOUND; guidance that omitting contextId starts a new conversation) |
| Absent | Absent | — | A new conversation |
Answering a question
When a task becomes input-required (TASK_STATE_INPUT_REQUIRED), send the answer as follows.
- 0.3: send it via
message/sendwith the samecontextId - 1.0: send it via
SendMessagewith the task'staskId. Sending with onlycontextIdreturns-32004with guidance to addtaskId
A reply sent as the continuation of a task waiting for an answer is recorded as the answer to that question automatically only when the waiting question has a question ID (metadata.interactionId) (you can answer even after the monthly usage limit is used up). For an answer chosen from the options, add metadata.optionIndex with the number of the chosen option (0 to 9, starting from 0). When the question has no ID, answer in text without metadata.optionIndex (it is not recorded as an answer). If the number is not an integer from 0 to 9 or is outside the options, or it is sent with a message that does not continue a task waiting for a question that has an ID, -32602 (INVALID_OPTION_INDEX) is returned.
Listing Tasks (ListTasks on 1.0)
Returns the tasks (requests) of one conversation. params.contextId (the conversation ID) is required. Without it, the response is -32004 with guidance to send contextId or use GetTask.
pageSizeis 1 to 100 (default 50)- Only when
includeArtifactsistrue, each task includes itsartifacts - Tasks are ordered by status time, newest first
- When the conversation does not exist or is not yours, an empty list is returned
Canceling
0.3 (tasks/cancel) | 1.0 (CancelTask) | |
|---|---|---|
params.id | The conversation ID | The task ID |
| In progress | Canceled | Canceled (when it is that task's execution) |
| Waiting for input | Cannot be canceled (-32002) | Canceled |
| Finished | Cannot be canceled (-32002) | Cannot be canceled (-32002) |
A canceled task is returned with the state canceled (TASK_STATE_CANCELED). On 1.0, -32002 is also returned when another request of the same conversation is the one in progress.
- A task can be canceled right after it was sent (before its response is saved). In that case, canceling can wait up to about 10 seconds
- If it still cannot be canceled,
-32603is returned with guidance to cancel again in a few seconds
Resubscribing
0.3 (tasks/resubscribe) | 1.0 (SubscribeToTask) | |
|---|---|---|
| First event | None (only events after reconnecting) | The task as of that moment |
| In progress | Streams that execution's events | Streams that execution's events |
| Waiting for input | -32001 (nothing is in progress) | Stays connected and, once an answer arrives and execution starts, streams its events |
| Finished | -32001 | -32004 (guidance to read the result with GetTask) |
On 1.0, SubscribeToTask sends the last status and closes when the task finishes (TASK_STATE_COMPLETED, TASK_STATE_CANCELED, or TASK_STATE_FAILED). When another question comes after an answer, it sends that status and stays connected. It waits at most 2 hours; after that it closes without sending a status. You can keep following the task with GetTask or SubscribeToTask.
Neither version resends the events that happened while disconnected one by one. On 1.0, the first task sent includes the artifacts and status up to that moment.
final on 0.3 streaming
On 0.3 message/stream and tasks/resubscribe, the event for the waiting-for-input (input-required) status has final: true, and the stream closes there. 1.0 has no final; the end is known when the stream closes. The final: true on 0.3 will be removed when 0.3 support ends.
Provided Skills
The skills exposed in the Agent Card:
execute_task
Send a task to the agent for autonomous execution in an isolated environment. Equivalent to agentMode: true (planning + tool use). Complex tasks take several minutes.
| Item | Details |
|---|---|
| Required scope | a2a:all, or a2a:connect with chat:exec (plus chat:file when attaching files) |
| Use case | Autonomous execution of multi-step tasks, deliverable generation |
| Attached files | Content parts (base64) only; URL parts are not supported. Up to 5 MB per file, 5 files, 20 MB in total. Files of an unaccepted type return -32005 (Content Type Not Supported) |
direct_llm
Query the LLM directly without planning or tool use. Equivalent to agentMode: false. Answers in seconds and returns no files.
| Item | Details |
|---|---|
| Required scope | a2a:all, or a2a:connect with chat:exec |
| Use case | One-shot processing such as knowledge Q&A, translation, summarization |
Reading answers and artifacts
- The final answer is the text of
status.messagein thecompletedstatus. The same text is also in an artifact whose ID starts withresult- - Files arrive as artifacts with a download URL (see "Retrieving Artifacts" below)
- A question is the text of
status.messagein theinput-requiredstatus. The same question is also in an artifact whose ID starts withinteraction-. Itsmetadata.interactionTypeis one ofchoice/confirmation/question, the ID of the question is inmetadata.interactionId(it may be absent), and when there are options they are inmetadata.options[](except forchoice, the options are also appended to the text inparts[0]asOptions: …). A turn that is waiting for a reply has noresult-artifact - On 0.3,
tasks/getandmessage/sendalso return the artifacts of earlier turns (such as theinteraction-of an earlier question). Tell turns apart byartifact.metadata.messageId(for file artifacts, by the<messageId>at the end ofartifactId) - A canceled or failed task is known by its state (
canceled/failedon 0.3,TASK_STATE_CANCELED/TASK_STATE_FAILEDon 1.0). Do not rely on its artifacts at that point. A newresult-orinteraction-is not necessarily created on cancel or failure, and earlier ones (such as theinteraction-sent when the task started waiting for input) or ones rebuilt when the task is read again (the question'sinteraction-, or aresult-with the partial text) may remain - An artifact whose ID starts with
ui-resource-is supplementary UI for people (see "UI Resources" below). When the UI cannot be returned, the artifact is left out entirely
Message Structure
The message shape follows the A2A specification. This product handles it as follows.
messageId(a new value for each message) androle("user"on 0.3,"ROLE_USER"on 1.0) are required. On 0.3, a missing one returns-32602- A text part is required. Several text parts are joined with line breaks into one instruction
- Data parts (
data) are not used as instructions. A message with no text (only files, only data, etc.) makes the task fail - Specify how to run with
metadata(see "Metadata" below)
Metadata
| Key | Default | Description |
|---|---|---|
agentMode | true | true: agent execution / false: LLM direct query |
agentLevel | "default" | default / high_performance |
reportMode | "with" | with: also creates a formatted work report (PDF) near the end of the run / without: skips only that report (the task itself and everything else returned are the same) |
personaKey | (not applied) | Specify a persona. If omitted, no persona is applied. An unknown key returns -32602 (INVALID_PERSONA_KEY) |
optionIndex | (none) | The number of the option chosen as the answer (0 to 9, starting from 0). Only on a reply that continues a task waiting for a question with a question ID (metadata.interactionId) (see Answering a question) |
All are optional and the same on 0.3 and 1.0. For details, see Connection Methods Guide - A2A execution parameters.
Retrieving Artifacts
Files produced by the agent are delivered as file parts in artifacts. The artifact itself does not carry the file contents; the download URL is file.uri on 0.3 and url on 1.0. The file name is in file.name on 0.3 and in filename on 1.0.
Fetch the download URL with a GET using the same Bearer token as A2A. A token with a2a:all, or with a2a:connect and chat:exec, can download it without any additional scope.
curl "<value of file.uri or url>" \
-H "Authorization: Bearer <access_token>" \
-o report.pdf
For endpoint details, see User API Reference — Artifact retrieval.
UI Resources
When the agent produces a UI (a chart, a map, a card list, etc.) during execution, it is delivered as an artifact whose artifactId starts with ui-resource-.
UI resources are supplementary output. The substantive output for that turn is in the result- artifact, or in the interaction- artifact if the turn ended with a question.
Not every UI produced during a run becomes an artifact. When the HTML cannot be served, that ui-resource- artifact is not delivered.
Retrieving the HTML
For type: "html", the HTML is not included in the artifact. Retrieve it from:
GET /api/v1/conversations/{contextId}/ui-resources/{tool_call_id}
contextId is on the event (it equals the conversation ID) and tool_call_id is parts[0].data.tool_call_id. Use the same Bearer token as A2A; a token with a2a:all, or with a2a:connect and chat:exec, can get it without any additional scope. See User API Reference — Get a UI resource for details.
For type: "data", the payload is included inline in parts[0].data.data, so no retrieval is needed.
The ui-resource- artifact of a draft card made in the chat has a second part (a data part), and its data.draft (parts[1].data.draft) holds the draft. Its shape and how to create it are the same as in Streaming guide — delta.draft.
UI that asks for a reply (choice cards or a question form) is not delivered as a ui-resource- artifact. It appears as the second part (a data part) of the artifact whose artifactId starts with interaction-. When the UI cannot be served, that part is absent and only the text in parts[0] remains. Send the reply as described in "Answering a question" above.
Never place the retrieved HTML into the model context (prompt-injection risk for external content, and no reasoning value for first-party content). Your application fetches it and renders it for a human.
For what to watch out for when rendering, see Streaming Guide — Notes on rendering.
Request Examples
SendMessage (1.0)
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/a2a \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-H "A2A-Version: 1.0" \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "SendMessage",
"params": {
"message": {
"messageId": "9b2f0c1e-4d8a-4f7e-a1b2-3c4d5e6f7a8b",
"role": "ROLE_USER",
"parts": [{ "text": "Please analyze the sales data" }],
"metadata": { "agentMode": true }
}
}
}'
In the response, result.task.id is the task ID and result.task.contextId is the conversation ID.
Errors
The error codes follow the A2A specification (A2A Specification). Error messages are written so that the other side (a person or an agent) can tell what to do next. The detail code is in error.data.code on 0.3 and in error.data[].metadata.code on 1.0.
| Detail code | code | When |
|---|---|---|
MISSING_SCOPE | -32600 | The scope needed for the operation is missing |
CONVERSATION_BUSY | -32600 | The same conversation is in progress |
ACCOUNT_SUSPENDED | -32600 | The user's use was suspended by an administrator |
FEATURE_NOT_PERMITTED | -32600 | An administrator has not permitted agent mode (metadata.agentMode is true, which is also the default when omitted) or file uploads |
TEXT_SEGMENT_TOO_LARGE | -32600 | A text part is too long |
PROJECT_CONVERSATION | -32600 | Sent to a conversation of a project run |
CONVERSATION_ARCHIVED | -32600 | Sent to an archived conversation (restore the conversation, then send again) |
CONVERSATION_NOT_FOUND | -32600 | On 0.3, sent to a conversation that does not exist or is not yours |
CONTEXT_NOT_FOUND | -32602 | On 1.0, sent a contextId of a conversation that does not exist or is not yours |
CONTEXT_TASK_MISMATCH | -32602 | On 1.0, taskId and contextId do not match |
FILE_URI_NOT_SUPPORTED | -32602 | Sent a file part by URL |
FILE_PROCESSING_FAILED | -32602 | The attached files cannot be accepted (size, count, etc.) |
INVALID_PERSONA_KEY | -32602 | Unknown personaKey |
INVALID_OPTION_INDEX | -32602 | metadata.optionIndex is not an integer from 0 to 9 or is outside the options of the question, or it was sent with a message that does not continue a task waiting for a question that has an ID |
INVALID_PAGE_SIZE, INVALID_TIMESTAMP, INVALID_PAGE_TOKEN | -32602 | Invalid ListTasks parameters |
INVALID_PARAMS | -32602 | A send on 1.0 has no message |
EXECUTION_TIMEOUT | -32603 | A blocking send exceeded the maximum execution time |
FEATURE_PERMISSIONS_UNAVAILABLE | -32603 | Feature permissions could not be checked (wait and retry) |
HTTP-layer errors:
| HTTP Status | Description |
|---|---|
401 Unauthorized | Access token invalid or expired |
403 Forbidden | Neither a2a:all nor a2a:connect, or a request to /api/v1/a2a was stopped by a security inspection in front of the API (error.code is waf_blocked) |
413 Payload Too Large | Request body exceeds the size limit |
503 Service Unavailable | Authentication is temporarily unavailable. Please retry later. If the problem persists, contact the service administrator |
See Also
- Connection Methods Guide - A2A — Agent Card example and use cases
- Authentication API Reference (SaaS) — Token acquisition
- A2A Specification — Full protocol details