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.

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/*)

Base URL: https://api.fd.agenticstar.tm.softbank.jp

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:exec`	Required to use A2A at all
`a2a:file`	Additionally required when attaching files via FilePart

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.

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:exec` (and `a2a:file` when attaching via FilePart)
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:exec`
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` / `medium_performance` / `low_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.

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.0" \
  -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.0" \
  -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

HTTP-layer errors:

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

Endpoints​

Authentication​

Request Headers​

JSON-RPC Methods​

Blocking vs Streaming​

Provided Skills​

execute_task​

direct_llm​

Message Structure​

Metadata​

Request Examples​

message/send (Blocking)​

message/stream (SSE)​

Get the Agent Card​

Error Codes​

See Also​