A2A API リファレンス（SaaS）

AGENTIC STAR SaaS版が提供する A2A（Agent-to-Agent Protocol） エンドポイントの詳細仕様です。A2A は Google A2A プロトコルに準拠した JSON-RPC 2.0 インターフェースで、エージェント間の連携や独自フロントからのタスク実行に利用します。

SaaS 版専用

本リファレンスのエンドポイントは SaaS 版でのみ提供 されます。Marketplace 版では A2A はビルド時に無効化されており、エンドポイントは存在しません。

接続方式の概要（Agent Card 例を含む）は 接続方式ガイド を参照してください。

エンドポイント

SaaS

メソッド	エンドポイント	説明
GET	/.well-known/agent-card.json	Agent Card 取得（スキル一覧・認証方式・ケイパビリティ）
POST	/api/v1/a2a	A2A JSON-RPC エンドポイント（message/send, message/stream, tasks/*）

ベース URL: https://api.fd.agenticstar.tm.softbank.jp

プロトコル: JSON-RPC 2.0（Blocking は application/json、Streaming は SSE）

認証

すべてのリクエストには Authorization: Bearer <access_token> ヘッダーが必須です。トークンには次のスコープが必要です。

スコープ	用途
a2a:exec	A2A 全体の利用（必須）
a2a:file	FilePart で添付ファイルを送信する場合に追加で必要

トークン取得方法は 認証 API リファレンス（SaaS） を参照してください。

リクエストヘッダー

ヘッダー	必須	説明
Authorization	✅	Bearer <access_token>
Content-Type	✅	application/json
A2A-Version	✅	A2A プロトコルバージョン。サーバー対応外のバージョンは -32600 で reject

JSON-RPC メソッド

メソッド	形式	説明
message/send	Blocking (JSON)	メッセージを送信し、完了まで待機して結果を取得
message/stream	Streaming (SSE)	メッセージを送信し、SSE で逐次イベントを受信
tasks/get	Blocking	タスクの状態を取得
tasks/cancel	Blocking	進行中のタスクをキャンセル
tasks/resubscribe	Streaming (SSE)	SSE 切断後に同タスクのストリーミングへ再接続（途中から再開）

Blocking と Streaming の違い

• Blocking (message/send, tasks/get, tasks/cancel): application/json で 1 レスポンスを返却。接続維持用のホワイトスペース ("\n") が定期的に送出される場合があります。
• Streaming (message/stream, tasks/resubscribe): text/event-stream (SSE) で逐次的にイベントを返却。接続維持用に : heartbeat\n\n の SSE コメントが定期送出されます。

提供スキル

Agent Card で公開しているスキルは以下のとおりです。

execute_task

エージェントにタスクを送信し、自律実行します。agentMode: true 相当（プランニング + ツール利用）。

項目	内容
必要スコープ	a2a:exec（FilePart 添付時は a2a:file も）
用途	複合タスクの自律実行・成果物生成

direct_llm

LLM に直接問い合わせを行います。agentMode: false 相当（プランニング・ツール利用なし）。

項目	内容
必要スコープ	a2a:exec
用途	知識ベース Q&A・翻訳・要約 等の単発処理

メッセージ構造

message/send / message/stream の params.message 構造:

JSON

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

メタデータ

キー	既定値	説明
agentMode	true	true: エージェント実行 / false: LLM 直接問い合わせ
agentLevel	"default"	default / high_performance / medium_performance / low_performance
reportMode	"with"	with: 進捗レポート付き / without: 結果のみ
personaKey	（未適用）	ペルソナ（応答人格）の指定。未指定時はペルソナを適用しない

いずれも省略可能。詳細は 接続方式ガイド - A2A 実行パラメータの指定 を参照してください。

リクエスト例

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": "売上データを分析してください" }],
        "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": "売上データを分析してください" }]
      }
    }
  }'

Agent Card 取得

curl

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

エラーコード

JSON-RPC 2.0 標準のエラーコード。

code	説明
-32700	Parse Error
-32600	Invalid Request（A2A-Version 非対応含む）
-32601	Method Not Found
-32602	Invalid Params
-32603	Internal Error

HTTP 層のエラー:

HTTP Status	説明
401 Unauthorized	アクセストークンが無効・期限切れ
403 Forbidden	必要なスコープが不足（a2a:exec / a2a:file）
413 Payload Too Large	リクエストサイズが上限超過

関連ドキュメント

• 接続方式ガイド - A2A — Agent Card 例とユースケース
• 認証 API リファレンス（SaaS） — トークン取得
• Google A2A 仕様 — プロトコル詳細