A2A API Reference (SaaS)

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 conforming to the Google A2A protocol, used for agent-to-agent collaboration and task execution from a custom frontend.

SaaS Edition Only

The endpoints in this reference are available only in the SaaS edition. On the Marketplace edition, A2A is disabled at build time and the endpoint does not exist.

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

Method	Endpoint	Description
GET	`/.well-known/agent-card.json`	Agent Card (skill list, auth scheme, capabilities)
POST	`/api/v1/a2a`	A2A JSON-RPC endpoint (message/send, message/stream, tasks/*)

Protocol: JSON-RPC 2.0 (Blocking uses application/json; Streaming uses SSE)

Authentication

All requests must include the Authorization: Bearer <access_token> header. The token requires the following scopes:

Scope	Purpose
`a2a:all`	Required to connect to the agent via A2A (includes file attachments)

For token acquisition, see the Authentication API Reference (SaaS).

Request Headers

Header	Required	Description
`Authorization`	✅	`Bearer <access_token>`
`Content-Type`	✅	`application/json`
`A2A-Version`	✅	A2A protocol version. Server-unsupported versions are rejected with `-32600`

JSON-RPC Methods

Method	Style	Description
`message/send`	Blocking (JSON)	Send a message and wait for the result
`message/stream`	Streaming (SSE)	Send a message and receive events incrementally over SSE
`tasks/get`	Blocking	Get the state of a task
`tasks/cancel`	Blocking	Cancel a running task
`tasks/resubscribe`	Streaming (SSE)	Reconnect to a task's stream after SSE disconnect (resumes from where it left off)

Blocking vs Streaming

Blocking (message/send, tasks/get, tasks/cancel): Returns a single application/json response. A keep-alive whitespace ("\n") may be sent periodically.
Streaming (message/stream, tasks/resubscribe): Returns events incrementally as text/event-stream (SSE). Keep-alive : heartbeat\n\n SSE comments are sent periodically.

`tasks/get` response

tasks/get returns the whole conversation as a single task (id is the conversation ID, the same value as contextId). artifacts contains the artifacts of every turn (deliverables, UI resources, interaction-, and result-). A message/send response for the same contextId likewise includes the artifacts of previous turns in artifacts, in addition to the current turn (the same content as tasks/get).

status.state

state	Meaning	`status.message`
`submitted`	The agent has not responded yet	None
`working`	Execution is in progress	Progress text
`input-required`	The agent is waiting for your reply (choice, confirmation, or question)	The question text. `metadata.interactionType` is one of `choice` / `confirmation` / `question`
`completed`	The last turn has finished	Summary text of the final answer

While input-required, the question is also delivered as an artifact whose artifactId starts with interaction- (see "UI Resources"). Reply via message/send with the same contextId. After you reply, the next tasks/get moves to working or completed. A turn that is waiting for a reply has no result- artifact.

historyLength

`params.historyLength`	`history` in the response
Not specified	The most recent 100 messages
Positive integer N	The most recent N messages
`0`	The `history` field is omitted

Any value other than 0 or a positive integer (negative, fractional, or string) is treated as not specified. configuration.historyLength on message/send / message/stream follows the same rule: 0 omits history from the returned task; otherwise history holds the single message you sent.

Provided Skills

The skills exposed in the Agent Card:

`execute_task`

Send a task to the agent for autonomous execution. Equivalent to agentMode: true (planning + tool use).

Item	Details
Required scope	`a2a:all`
Use case	Autonomous execution of multi-step tasks, deliverable generation

`direct_llm`

Query the LLM directly without planning or tool use. Equivalent to agentMode: false.

Item	Details
Required scope	`a2a:all`
Use case	One-shot processing such as knowledge Q&A, translation, summarization

Message Structure

The params.message structure for message/send / message/stream:

JSON
{
  "message": {
    "parts": [
      { "kind": "text", "text": "..." }
    ],
    "metadata": {
      "agentMode": true,
      "agentLevel": "default",
      "reportMode": "with",
      "personaKey": "concise"
    }
  }
}

Metadata

Key	Default	Description
`agentMode`	`true`	`true`: agent execution / `false`: LLM direct query
`agentLevel`	`"default"`	`default` / `high_performance`
`reportMode`	`"with"`	`with`: with progress reports / `without`: result only
`personaKey`	(not applied)	Specify a persona. If omitted, no persona is applied

All are optional. For details, see Connection Methods Guide - A2A execution parameters.

Retrieving Artifacts

Files produced by the agent are delivered as file parts in artifact-update events. The artifact itself does not carry the file contents — file.uri is the download URL.

JSON
{
  "kind": "artifact-update",
  "artifact": {
    "artifactId": "file-report.pdf-<messageId>",
    "name": "report.pdf",
    "parts": [
      {
        "kind": "file",
        "file": {
          "uri": "https://api.fd.agenticstar.tm.softbank.jp/api/v1/files/proxy?path=...",
          "mimeType": "application/pdf"
        }
      }
    ],
    "metadata": { "filepath": "...", "source": "agent", "isPrimary": true, "size": 4201846 }
  }
}

Fetch file.uri with a GET using the same Bearer token as A2A. The a2a:all scope is sufficient; no additional scope is required.

curl
curl "<value of file.uri>" \
  -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-.

Item	Content
`artifact.name`	The fixed label `"UI resource"`
`artifact.parts[0]`	A data part (`kind: "data"`) holding the UI resource metadata
`artifact.metadata.messageId`	Groups artifacts by conversation turn

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. The object has the same structure as in SSE; for field details, see Streaming Guide — delta.uiResource.

Not every UI produced during a run becomes an artifact. When the HTML cannot be served, that ui-resource- artifact is not delivered.

parts[0].data.altText is the alternative text (what it contains depends on origin — see Streaming Guide — Differences by origin). On message/stream it is the same string as the preceding working status update, so if you are accumulating progress text, use only one of the two. On message/send and tasks/get, the working updates are not retained, so altText is the only place the summary appears.

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 — a2a:all is sufficient and no additional scope is required. The response is JSON ({ toolCallId, type, origin, mimeType, html }); see User API Reference — Get a UI resource for details.

curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/<contextId>/ui-resources/<tool_call_id>" \
  -H "Authorization: Bearer <access_token>"

For type: "data", the payload is included inline in parts[0].data.data, so no retrieval is needed.

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 (kind: "data") 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. Reply via message/send with the same contextId.

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

`message/send` (Blocking)

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: 0.3" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "message/send",
    "params": {
      "message": {
        "parts": [{ "kind": "text", "text": "Please analyze the sales data" }],
        "metadata": { "agentMode": true }
      }
    }
  }'

`message/stream` (SSE)

curl
curl -N -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: 0.3" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "message/stream",
    "params": {
      "message": {
        "parts": [{ "kind": "text", "text": "Please analyze the sales data" }]
      }
    }
  }'

Get the Agent Card

curl
curl https://api.fd.agenticstar.tm.softbank.jp/.well-known/agent-card.json

Error Codes

Standard JSON-RPC 2.0 error codes.

code	Description
`-32700`	Parse Error
`-32600`	Invalid Request (including unsupported A2A-Version)
`-32601`	Method Not Found
`-32602`	Invalid Params
`-32603`	Internal Error
`-32001`	Task Not Found (the specified task does not exist or is not permitted)
`-32005`	Content Type Not Supported (unsupported file type)

HTTP-layer errors:

HTTP Status	Description
`401 Unauthorized`	Access token invalid or expired
`403 Forbidden`	Required scope missing (`a2a:all`)
`413 Payload Too Large`	Request body exceeds the size limit

Base URL​

Endpoints​

Authentication​

Request Headers​

JSON-RPC Methods​

Blocking vs Streaming​

tasks/get response​

Provided Skills​

execute_task​

direct_llm​

Message Structure​

Metadata​

Retrieving Artifacts​

UI Resources​

Retrieving the HTML​

Request Examples​

message/send (Blocking)​

message/stream (SSE)​

Get the Agent Card​

Error Codes​

See Also​