A2A API リファレンス（SaaS）

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

SaaS 版専用

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

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

ベース URL

すべてのリクエストは以下のベース URL に対して送信します。

SaaS

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

エンドポイント

SaaS

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

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

認証

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

スコープ	用途
`a2a:all`	A2A（Agent-to-Agent）プロトコルでエージェントに接続（ファイル添付を含む）

トークン取得方法は認証 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 コメントが定期送出されます。

`tasks/get` の応答

tasks/get は会話全体を 1 つのタスクとして返します（id は contextId と同じ会話 ID）。artifacts には全ターンの artifact（成果物・UI リソース・interaction-・result-）が含まれます。同じ contextId に対する message/send の応答でも、artifacts には当ターン分に加えて過去ターンの artifact が含まれます（tasks/get と同じ内容）。

status.state

state	意味	`status.message`
`submitted`	エージェントの応答がまだありません	なし
`working`	実行中です	進捗テキスト
`input-required`	エージェントが回答を待っています（選択肢・確認・質問）	質問文。`metadata.interactionType` は `choice` / `confirmation` / `question` のいずれか
`completed`	最後のターンが完了しています	最終回答の要約テキスト

input-required のとき、その質問は interaction- で始まる artifact にも入ります（「UI リソース」の節を参照）。回答は同じ contextId を指定して message/send で送ります。回答後の tasks/get は working または completed に遷移します。回答を待っているターンには result- artifact は付きません。

historyLength

`params.historyLength`	応答の `history`
未指定	直近 100 件
正の整数 N	直近 N 件
`0`	`history` フィールドを省略

0 と正の整数以外の値（負数・小数・文字列）は未指定と同じ扱いです。message/send / message/stream の configuration.historyLength も同じ規則で、0 を指定すると応答のタスクから history が省略され、それ以外では送信したメッセージ 1 件が history に入ります。

提供スキル

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

`execute_task`

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

項目	内容
必要スコープ	`a2a:all`
用途	複合タスクの自律実行・成果物生成

`direct_llm`

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

項目	内容
必要スコープ	`a2a:all`
用途	知識ベース 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`
`reportMode`	`"with"`	`with`: 進捗レポート付き / `without`: 結果のみ
`personaKey`	（未適用）	ペルソナ（応答人格）の指定。未指定時はペルソナを適用しない

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

成果物の取得

エージェントが生成したファイルは、artifact-update イベントの file part として通知されます。artifact 自体にファイルの中身は含まれず、file.uri がダウンロード用の 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 }
  }
}

file.uri はA2A と同じ Bearer トークンで GET します。a2a:all のスコープのままダウンロードでき、追加のスコープは必要ありません。

curl
curl "<file.uri の値>" \
  -H "Authorization: Bearer <access_token>" \
  -o report.pdf

エンドポイントの詳細はユーザー API リファレンス — 成果物取得を参照してください。

UI リソース

エージェントが実行中に UI（グラフ・地図・カード一覧など）を生成した場合、artifactId が ui-resource- で始まる artifact として通知されます。

項目	内容
`artifact.name`	固定ラベル `"UI resource"`
`artifact.parts[0]`	`kind: "data"` の data part。UI リソースのメタ情報が入ります
`artifact.metadata.messageId`	会話ターンごとのグループ化に使います

UI リソースは補助的な出力です。そのターンの実質的な出力は result- artifact（回答が質問で終わった場合は interaction- artifact）にあります。オブジェクトの構造は SSE と同一で、フィールドの詳細はストリーミングガイド — delta.uiResource を参照してください。

実行中に生成された UI がすべて artifact になるとは限りません。HTML を提供できない場合、その ui-resource- artifact は配信されません。

parts[0].data.altText は代替テキストです（内容は origin によって変わります。ストリーミングガイド — origin による違いを参照してください）。message/stream では直前の working ステータス更新と同一文字列になるため、進捗テキストを蓄積している場合はどちらか一方だけを使ってください。message/send と tasks/get では working の更新が保持されないため、altText が要約を得られる唯一の場所になります。

HTML の取得

type: "html" の場合、HTML は artifact に含まれません。以下のエンドポイントで取得します。

GET /api/v1/conversations/{contextId}/ui-resources/{tool_call_id}

contextId はイベントに含まれる値（会話 ID と同一）、tool_call_id は parts[0].data.tool_call_id です。A2A と同じ Bearer トークンで取得でき、a2a:all のままで追加スコープは不要です。応答は JSON（{ toolCallId, type, origin, mimeType, html }）で、詳細はユーザー API リファレンス — UI リソース取得を参照してください。

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

type: "data" の場合はペイロードが parts[0].data.data にインラインで含まれるため、取得は不要です。

入力を求める UI（選択肢カードや質問フォーム）は ui-resource- ではなく interaction- で始まる artifact の 2 番目の part（kind: "data"）に入ります。UI が提供できない場合はこの part が付かず、parts[0] のテキストだけになります。回答は同じ contextId を指定して message/send で送ります。

HTML をモデルに渡さないでください

取得した HTML をモデルのコンテキストに入れないでください（外部コンテンツではプロンプトインジェクションのリスクがあり、自社由来でも推論上の価値はありません）。取得した HTML は、アプリケーション側で人間に向けて描画するものです。

描画時の注意はストリーミングガイド — 描画時の注意を参照してください。

リクエスト例

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

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
`-32001`	Task Not Found（指定タスクが存在しない、またはアクセス権がない）
`-32005`	Content Type Not Supported（サポートされないファイル形式）

HTTP 層のエラー:

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

ベース URL​

エンドポイント​

認証​

リクエストヘッダー​

JSON-RPC メソッド​

Blocking と Streaming の違い​

tasks/get の応答​

提供スキル​

execute_task​

direct_llm​

メッセージ構造​

メタデータ​

成果物の取得​

UI リソース​

HTML の取得​

リクエスト例​

message/send（Blocking）​

message/stream（SSE）​

Agent Card 取得​

エラーコード​

関連ドキュメント​