# 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)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/a2a-ref.md).
>
> For a connection-method overview (including an Agent Card example), see the [Connection Methods Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/connection-guide.md#a2aagent-to-agent-protocol).

## Base URL

All requests are sent to the following base URL.

SaaS

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

## Endpoints

SaaS

| 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 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.

| 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)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/auth-saas-ref.md).

## 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/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.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.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.

| `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/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.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, `-32603` is 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.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

| 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](#answering-a-question)) |

All are optional and the same on 0.3 and 1.0. For details, see [Connection Methods Guide - A2A execution parameters](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/connection-guide.md#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.

```bash
curl "<value of file.uri or url>" \
  -H "Authorization: Bearer <access_token>" \
  -o report.pdf
```

For endpoint details, see [User API Reference — Artifact retrieval](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference.md#get-artifact).

## 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:

```text
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](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference.md#get-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](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/streaming-guide.md#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](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/streaming-guide.md#rendering-notes).

## Request Examples

### `SendMessage` (1.0)

```bash
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](https://a2a-protocol.org/latest/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](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/connection-guide.md#a2aagent-to-agent-protocol) — Agent Card example and use cases
- [Authentication API Reference (SaaS)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/auth-saas-ref.md) — Token acquisition
- [A2A Specification](https://a2a-protocol.org/latest/specification/) — Full protocol details
