Skip to main content

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.

Marketplace edition

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.

SaaS
https://api.fd.agenticstar.tm.softbank.jp

Endpoints​

SaaS
MethodEndpointDescription
GET/.well-known/agent-card.jsonAgent Card (skill list, auth scheme, capabilities). No token is required
POST/api/v1/a2aA2A 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-VersionVersion
Not sent0.3
0.30.3
1.01.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 by contextId instead

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.

ScopeWhat it allows
a2a:allEvery A2A operation (including file attachments and listing)
a2a:connectConnecting 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).

OperationRequired 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 attachedchat: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.31.0StyleDescription
message/sendSendMessageBlocking (JSON)Send a message and wait until it finishes or waits for input, then return the result
message/streamSendStreamingMessageStreaming (SSE)Send a message and receive events incrementally over SSE
tasks/getGetTaskBlocking (JSON)Get the state of a task
—ListTasksBlocking (JSON)List the tasks of one conversation (1.0 only)
tasks/cancelCancelTaskBlocking (JSON)Cancel a task
tasks/resubscribeSubscribeToTaskStreaming (SSE)Reconnect to the same task's stream after a disconnect

The push notification configuration methods are not supported (-32003).

  • Blocking sends (message/send and SendMessage) wait until the run finishes or waits for an answer. On 0.3, message/send always waits, regardless of the value of configuration.blocking
  • With configuration.returnImmediately set to true on SendMessage (1.0), the task is returned right away as accepted (TASK_STATE_SUBMITTED). Follow it with GetTask or SubscribeToTask

Task Shape​

What a task covers differs by version.

0.31.0
One taskThe whole conversationOne request (one user message and the response to it; continuing after answering a question stays in the same task)
Task IDThe conversation ID (same as contextId)An ID per request
contextIdThe conversation IDThe 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.message is the question, and metadata.interactionType is one of choice, confirmation, and question. The ID of the question is in metadata.interactionId (it may be absent)
  • On 0.3, the artifacts of tasks/get and message/send also include those of earlier turns (because a task is the whole conversation). On 1.0, the artifacts and history of GetTask cover that request only
  • For get (tasks/get and GetTask) and list (ListTasks), history holds the most recent 100 messages when historyLength is not sent. The task in a send response holds only the message you sent in history. In both cases, historyLength set to 0 returns no history

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.

taskIdcontextIdTarget request (without taskId, the latest request of the conversation)Result
PresentAbsent, or same as the conversationWaiting for inputContinues (same task)
PresentAbsent, or same as the conversationIn progress-32600 (CONVERSATION_BUSY)
PresentAbsent, or same as the conversationFinished-32004 (a finished task takes no more messages; guidance to send a new request with contextId)
PresentDifferent from the conversation—-32602 (CONTEXT_TASK_MISMATCH)
Unknown or malformed——-32001 (Task Not Found)
AbsentPresent (your conversation)Waiting for input-32004 (guidance to answer with taskId)
AbsentPresent (your conversation)In progress-32600 (CONVERSATION_BUSY)
AbsentPresent (your conversation)Finished, or no request yetA new request in the same conversation (an archived conversation cannot be sent to; omit contextId to start a new conversation)
AbsentUnknown, or not your conversation—-32602 (CONTEXT_NOT_FOUND; guidance that omitting contextId starts a new conversation)
AbsentAbsent—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/send with the same contextId
  • 1.0: send it via SendMessage with the task's taskId. Sending with only contextId returns -32004 with guidance to add taskId

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.

  • pageSize is 1 to 100 (default 50)
  • Only when includeArtifacts is true, each task includes its artifacts
  • 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.idThe conversation IDThe task ID
In progressCanceledCanceled (when it is that task's execution)
Waiting for inputCannot be canceled (-32002)Canceled
FinishedCannot 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, -32603 is returned with guidance to cancel again in a few seconds

Resubscribing​

0.3 (tasks/resubscribe)1.0 (SubscribeToTask)
First eventNone (only events after reconnecting)The task as of that moment
In progressStreams that execution's eventsStreams 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.

ItemDetails
Required scopea2a:all, or a2a:connect with chat:exec (plus chat:file when attaching files)
Use caseAutonomous execution of multi-step tasks, deliverable generation
Attached filesContent 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.

ItemDetails
Required scopea2a:all, or a2a:connect with chat:exec
Use caseOne-shot processing such as knowledge Q&A, translation, summarization

Reading answers and artifacts​

  • The final answer is the text of status.message in the completed status. The same text is also in an artifact whose ID starts with result-
  • Files arrive as artifacts with a download URL (see "Retrieving Artifacts" below)
  • A question is the text of status.message in the input-required status. The same question is also in an artifact whose ID starts with interaction-. Its metadata.interactionType is one of choice / confirmation / question, the ID of the question is in metadata.interactionId (it may be absent), and when there are options they are in metadata.options[] (except for choice, the options are also appended to the text in parts[0] as Options: …). A turn that is waiting for a reply has no result- artifact
  • On 0.3, tasks/get and message/send also return the artifacts of earlier turns (such as the interaction- of an earlier question). Tell turns apart by artifact.metadata.messageId (for file artifacts, by the <messageId> at the end of artifactId)
  • A canceled or failed task is known by its state (canceled / failed on 0.3, TASK_STATE_CANCELED / TASK_STATE_FAILED on 1.0). Do not rely on its artifacts at that point. A new result- or interaction- is not necessarily created on cancel or failure, and earlier ones (such as the interaction- sent when the task started waiting for input) or ones rebuilt when the task is read again (the question's interaction-, or a result- 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) and role ("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​

KeyDefaultDescription
agentModetruetrue: 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
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.

Do not pass the HTML to the model

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
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 codecodeWhen
MISSING_SCOPE-32600The scope needed for the operation is missing
CONVERSATION_BUSY-32600The same conversation is in progress
ACCOUNT_SUSPENDED-32600The user's use was suspended by an administrator
FEATURE_NOT_PERMITTED-32600An administrator has not permitted agent mode (metadata.agentMode is true, which is also the default when omitted) or file uploads
TEXT_SEGMENT_TOO_LARGE-32600A text part is too long
PROJECT_CONVERSATION-32600Sent to a conversation of a project run
CONVERSATION_ARCHIVED-32600Sent to an archived conversation (restore the conversation, then send again)
CONVERSATION_NOT_FOUND-32600On 0.3, sent to a conversation that does not exist or is not yours
CONTEXT_NOT_FOUND-32602On 1.0, sent a contextId of a conversation that does not exist or is not yours
CONTEXT_TASK_MISMATCH-32602On 1.0, taskId and contextId do not match
FILE_URI_NOT_SUPPORTED-32602Sent a file part by URL
FILE_PROCESSING_FAILED-32602The attached files cannot be accepted (size, count, etc.)
INVALID_PERSONA_KEY-32602Unknown personaKey
INVALID_OPTION_INDEX-32602metadata.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-32602Invalid ListTasks parameters
INVALID_PARAMS-32602A send on 1.0 has no message
EXECUTION_TIMEOUT-32603A blocking send exceeded the maximum execution time
FEATURE_PERMISSIONS_UNAVAILABLE-32603Feature permissions could not be checked (wait and retry)

HTTP-layer errors:

HTTP StatusDescription
401 UnauthorizedAccess token invalid or expired
403 ForbiddenNeither 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 LargeRequest body exceeds the size limit
503 Service UnavailableAuthentication is temporarily unavailable. Please retry later. If the problem persists, contact the service administrator

See Also​