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

> **Where A2A is available**
>
> 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` (a request without a valid token gets `401 Unauthorized` first). For how to open them, see the [Helm Values Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/build/reference/helm-values-ref.md) in the Build section.

## Base URL

All requests are sent to the following base URL. Replace `<your-domain>` with the domain of your environment.

Marketplace

`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 (you can read the list of registered Agent IDs with `GET /v1/marketplace-agents`; there is no endpoint that lists published workflows).

| 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 `url` and `supportedInterfaces`, 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
- `agentId` is the ID of an Agent the administrator registered in the admin console. You can read the list with `marketplaceAgentId` of `GET /v1/marketplace-agents` (where the A2A endpoint is enabled, use it as is for `{agentId}` of the Agent Card and the endpoint)
- `projectId` is 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](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/auth-mp-ref.md)) | `tokenUrl` of `oauth2ClientCredentials`                                                                      |
| A user token of an application (sign-in from an external tool) | Authorization Code flow ([Authentication Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/auth-guide.md))                                                                                          | `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](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/setup-guide.md))
- 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)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/a2a-ref.md).

## 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 participants of that project (owners, operators and members) and people with the organization operations role. Anyone else is rejected with `project_not_found`. Only owners, operators and people with the organization operations role can stop a run someone else started

### 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 `messageId` and the same input, no new run starts and the earlier run is returned. With the same `messageId` and different input, the send is rejected
- A send with `taskId` is rejected (each message starts a new run). If that run exists the response is `-32004`, otherwise `-32001`
- `contextId` is always the `projectId`. 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. For a person with the organization operations role who does not take part in the project, `status.message` is absent (only when the step that finished last was closed by cancellation, it holds that mark, `cancelled`).

### Getting and listing

- `params.id` of get (`tasks/get` / `GetTask`) is the task ID (the run ID) returned when you sent the message
- List (`ListTasks` on 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), and `pageToken` reads the next page. The state may lag behind get by up to about 1 minute

### Canceling

Cancel (`tasks/cancel` / `CancelTask`) cancels the run (the same as [Cancel a Workflow Run](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/user-api-reference-projects.md#cancel-run)). `params.id` is the task ID returned when you sent the message (the run ID).

| Run state                                  | Response                                                                          |
| ------------------------------------------ | --------------------------------------------------------------------------------- |
| Running or awaiting review                 | Cancels it and returns the task with the state `canceled` (`TASK_STATE_CANCELED`) |
| Finished (including after it was canceled) | `-32002` (Task Not Cancelable)                                                    |
| Unknown or malformed ID                    | `-32001` (Task Not Found)                                                         |

- A cancel cannot be undone. Review requests that have not been decided are withdrawn, and the Agents of running steps are told to stop
- Canceling the same task again returns `-32002`

### What is not supported

| Operation                                                                                                         | Response                     |
| ----------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| Streaming (`message/stream` / `SendStreamingMessage`) and resubscribing (`tasks/resubscribe` / `SubscribeToTask`) | `-32004` (no run is started) |
| Push notification configuration                                                                                   | `-32003`                     |

## Errors

The error numbers are the same as in the SaaS edition ([A2A API Reference (SaaS) — Errors](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/a2a-ref.md#errors)). `MISSING_SCOPE` is not returned because scopes are not checked, and `INVALID_PERSONA_KEY` is not returned because `personaKey` is not used. The codes specific to the Marketplace edition are as follows. The detailed code is in `error.data.code` for 0.3 and in `error.data[].metadata.code` for 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 neither a member nor a person with the organization operations role  | `-32602` (`project_not_found`)             | `404` (`project_not_found`) |
| A member who is neither an owner nor an operator and does not have the organization operations role stopped a run someone else started | `-32600` (`operator_only`)                 | —                           |
| An administrator has suspended the user a published workflow runs as                                                                   | `-32600` (`PRINCIPAL_SUSPENDED`)           | —                           |
| An administrator has stopped the project of a published workflow, or a registered Agent placed in it                                   | `-32600` (`ADMIN_STOPPED`)                 | —                           |
| The first definition of the project of a published workflow is waiting for approval                                                    | `-32600` (`DEFINITION_PENDING`)            | —                           |
| References missing after the import remain in the project of a published workflow (it cannot start until they are reconnected)         | `-32600` (`RELINK_REQUIRED`)               | —                           |
| 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)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/a2a-ref.md) — Details of methods, task shape, and errors
- [Authentication API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/auth-mp-ref.md) — The standard token endpoint
- [API Setup Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/setup-guide.md) — Preparing service accounts and sign-in from an external tool
- [A2A Specification](https://a2a-protocol.org/latest/specification/) — Full protocol details
