A2A API リファレンス
AGENTIC STAR SaaS版が提供する A2A(Agent-to-Agent Protocol) エンドポイントの詳細仕様です。A2A は JSON-RPC 2.0 のインターフェースで、エージェント間の連携や独自フロントからのタスク実行に利用します。A2A の 0.3 と 1.0 の両方に対応しています。
このページは SaaS 版の A2A です。Marketplace 版の A2A は A2A API リファレンス(Marketplace 版) を参照してください。
接続方式の概要(Agent Card 例を含む)は 接続方式ガイド を参照してください。
ベース URL
すべてのリクエストは以下のベース URL に対して送信します。
https://api.fd.agenticstar.tm.softbank.jpエンドポイント
| メソッド | エンドポイント | 説明 |
|---|---|---|
| GET | /.well-known/agent-card.json | Agent Card 取得(スキル一覧・認証方式・ケイパビリティ)。トークンは要りません |
| POST | /api/v1/a2a | A2A JSON-RPC エンドポイント(0.3 と 1.0 のメソッド) |
プロトコル: JSON-RPC 2.0(待つ送信は application/json、ストリーミングは SSE)。gRPC と HTTP+JSON の形はありません。
Agent Card
Agent Card は版で 2 種類あります。リクエストヘッダー A2A-Version: 1.0 を付けると 1.0 の形だけの Agent Card、付けないか別の値のときは 0.3 と 1.0 の両方の項目を持つ 1 枚の Agent Card が返ります。どちらも、同じ /api/v1/a2a を 1.0 と 0.3 の口として載せています(supportedInterfaces)。
Agent Card のスキルの説明は短い要約です。細かい使い方はこのページにあり、Agent Card の documentationUrl はこのページ(英語)を指します。
版
リクエストヘッダー A2A-Version で、A2A のどの版で話すかを決めます。
A2A-Version | 版 |
|---|---|
| 付けない | 0.3 |
0.3 | 0.3 |
1.0 | 1.0 |
それ以外(2.0・0.3.0 など) | -32009(版に対応していない)で断ります |
- タスク ID は版の間で使い回せません。0.3 のタスク ID を 1.0 で送ると
-32001(Task Not Found)で、続けるにはcontextIdを使うよう案内します
認証
すべてのリクエストには Authorization: Bearer <access_token> ヘッダーが必須です(Agent Card の取得を除く)。トークンには a2a:all か a2a:connect のスコープが必要です。
| スコープ | できること |
|---|---|
a2a:all | A2A のすべての操作(ファイル添付と一覧を含む) |
a2a:connect | A2A のエンドポイントにつなぐ。操作ごとに、下の表のスコープも必要です |
a2a:connect のときに、操作ごとに必要なスコープは次のとおりです(REST の同じ操作と同じスコープです)。
| 操作 | 必要なスコープ |
|---|---|
送る(message/send・message/stream・SendMessage・SendStreamingMessage)・取る(tasks/get・GetTask)・止める(tasks/cancel・CancelTask)・つなぎ直す(tasks/resubscribe・SubscribeToTask) | chat:exec |
| ファイルを添えて送る | chat:exec と chat:file |
一覧(ListTasks) | chat:history |
足りないときは -32600(細かい印 MISSING_SCOPE)で、必要なスコープと次にすることを返します。新しく作るアプリには、a2a:connect と、使う機能のスコープを付けることをおすすめします。
A2A のスコープは、アプリケーション(Authorization Code フロー)で選べます。システム連携(Client Credentials フロー)では選べません。
トークン取得方法は 認証 API リファレンス(SaaS) を参照してください。
JSON-RPC メソッド
| 0.3 | 1.0 | 形式 | 説明 |
|---|---|---|---|
message/send | SendMessage | 待つ(JSON) | メッセージを送信し、終わるか質問待ちになるまで待って結果を返します |
message/stream | SendStreamingMessage | ストリーミング(SSE) | メッセージを送信し、SSE で逐次イベントを受信します |
tasks/get | GetTask | 待つ(JSON) | タスクの状態を取得します |
| ― | ListTasks | 待つ(JSON) | 1 つの会話のタスクの一覧を取得します(1.0 だけ) |
tasks/cancel | CancelTask | 待つ(JSON) | タスクを止めます |
tasks/resubscribe | SubscribeToTask | ストリーミング(SSE) | 切れた後に、同じタスクのストリーミングにつなぎ直します |
プッシュ通知の設定のメソッドは使えません(-32003)。
- 待つ送信(
message/send・SendMessage)は、終わるか質問待ちになるまで待ちます。0.3 のmessage/sendは、configuration.blockingの値によらず待ちます - 1.0 の
SendMessageでconfiguration.returnImmediatelyをtrueにすると、受け付けた時点のタスク(TASK_STATE_SUBMITTED)をすぐ返します。続きはGetTaskかSubscribeToTaskで追います
タスクの形
タスクの範囲は版で違います。
| 0.3 | 1.0 | |
|---|---|---|
| 1 つのタスク | 会話全体 | 1 回の依頼(利用者のメッセージ 1 つと、それへの応答。質問待ちに答えた続きも同じタスク) |
| タスク ID | 会話 ID(contextId と同じ) | 依頼ごとの ID |
contextId | 会話 ID | 会話 ID |
タスク ID と contextId は、中を読まない値として扱ってください(形は予告なく変わることがあります)。
- 状態の名前は規格どおりです。このエンドポイントは
rejected(TASK_STATE_REJECTED)を返しません - 質問待ち(
input-required・TASK_STATE_INPUT_REQUIRED)のstatus.messageは質問の文で、metadata.interactionTypeにchoice・confirmation・questionのどれかが入ります。質問の ID はmetadata.interactionIdに入ります(無い場合があります) - 0.3 の
tasks/getとmessage/sendのartifactsには、前のターンの分も入ります(タスクが会話全体のため)。1.0 のGetTaskのartifacts・historyは、その依頼の分だけです - 取る(
tasks/get・GetTask)と一覧(ListTasks)のhistoryは、historyLengthを付けないと直近 100 件です。送る応答のタスクのhistoryは、送ったメッセージ 1 件です。どちらも、historyLengthを0にするとhistoryは入りません
送り先の決まり
0.3 では、送り先の会話を taskId、metadata.conversationId、contextId の順に見て決めます。どれも無ければ新しい会話です。
1.0 では、taskId と contextId の組み合わせで決まります。metadata.conversationId は読みません。
taskId | contextId | 対象の依頼(taskId が無いときは、その会話のいちばん新しい依頼) | 動き |
|---|---|---|---|
| あり | なし・会話と同じ | 質問待ち | 続き(同じタスク) |
| あり | なし・会話と同じ | 実行中 | -32600(CONVERSATION_BUSY) |
| あり | なし・会話と同じ | 終わっている | -32004(終わったタスクには送れない。contextId で新しい依頼を送るよう案内) |
| あり | 会話と違う | ― | -32602(CONTEXT_TASK_MISMATCH) |
| 無い・形が合わない | ― | ― | -32001(Task Not Found) |
| なし | あり(自分の会話) | 質問待ち | -32004(答えるには taskId を付けるよう案内) |
| なし | あり(自分の会話) | 実行中 | -32600(CONVERSATION_BUSY) |
| なし | あり(自分の会話) | 終わっている・依頼が無い | 同じ会話の新しい依頼(アーカイブした会話には送れません。新しい会話にするときは contextId を外します) |
| なし | 無い・自分のものでない会話 | ― | -32602(CONTEXT_NOT_FOUND。contextId を外すと新しい会話になる、と案内) |
| なし | なし | ― | 新しい会話 |
質問への答え方
タスクが input-required(TASK_STATE_INPUT_REQUIRED)になったら、答えを次のように送ります。
- 0.3: 同じ
contextIdを付けてmessage/sendで送ります - 1.0: 同じタスクの
taskIdを付けてSendMessageで送ります。contextIdだけを付けて送ると-32004で、taskIdを付けるよう案内します
答えを待つタスクの続きとして送った返信は、待っている質問に質問の ID(metadata.interactionId)があるときだけ、自動でその質問への答えとして記録されます(月の利用の枠の上限に達していても答えられます)。選択肢から選んだ答えなら、metadata.optionIndex に選んだ選択肢の番号(0〜9。最初が 0)を付けます。質問の ID が無いときは、metadata.optionIndex を付けずに文で答えます(答えとしては記録されません)。番号が 0〜9 の整数ではない・選択肢の外、または質問の ID のある質問を待つタスクの続きではない送信に付けたときは -32602(INVALID_OPTION_INDEX)です。
一覧(1.0 の ListTasks)
1 つの会話のタスク(依頼)の一覧を返します。params.contextId(会話 ID)が必須です。無いときは -32004 で、contextId を付けるか GetTask を使うよう案内します。
pageSizeは 1〜100 です(既定 50)includeArtifactsがtrueのときだけ、各タスクのartifactsを含めます- 並びは状態の時刻の新しい順です
- 会話が無い・自分のものでないときは、空の一覧を返します
止める
0.3(tasks/cancel) | 1.0(CancelTask) | |
|---|---|---|
params.id | 会話 ID | タスク ID |
| 実行中 | 止めます | 止めます(そのタスクの実行のとき) |
| 質問待ち | 止められません(-32002) | 止めます |
| 終わっている | 止められません(-32002) | 止められません(-32002) |
止めると、状態が canceled(TASK_STATE_CANCELED)のタスクを返します。1.0 で、同じ会話の別の依頼が実行中のときも -32002 です。
- 送った直後(応答がまだ保存される前)でも止められます。そのときは、止めるのに 10 秒ほどまで待つことがあります
- それでも止められないときは
-32603で、数秒後にもう一度止めるよう案内します
つなぎ直す
0.3(tasks/resubscribe) | 1.0(SubscribeToTask) | |
|---|---|---|
| 最初に送るもの | なし(つないだ後の出来事だけ) | その時点のタスク |
| 実行中 | その実行の出来事を流します | その実行の出来事を流します |
| 質問待ち | -32001(実行中でないため) | つないだまま待ち、答えが届いて実行が始まったら、その出来事を流します |
| 終わっている | -32001 | -32004(GetTask で結果を読むよう案内) |
1.0 の SubscribeToTask は、タスクが終わる(TASK_STATE_COMPLETED・TASK_STATE_CANCELED・TASK_STATE_FAILED)と最後の状態を送って閉じます。答えの後にまた質問になったときは、その状態を送ってつないだまま待ちます。待つのは最大 2 時間で、超えると状態を送らずに閉じます。その後も GetTask か SubscribeToTask で続きを追えます。
どちらの版も、切れている間の出来事を 1 つずつ送り直すことはしません。1.0 では、最初に送るタスクに、その時点までの artifact と状態が入ります。
0.3 のストリーミングの final
0.3 の message/stream・tasks/resubscribe では、質問待ち(input-required)の状態の出来事は final: true で、そこでストリームが閉じます。1.0 には final が無く、ストリームが閉じることで終わりが分かります。0.3 での final: true は、0.3 への対応をやめるときに外します。
提供スキル
Agent Card で公開しているスキルは以下のとおりです。
execute_task
エージェントにタスクを送信し、隔離された環境で自律実行します。agentMode: true 相当(プランニング + ツール利用)。複雑なタスクは数分かかります。
| 項目 | 内容 |
|---|---|
| 必要スコープ | a2a:all、または a2a:connect と chat:exec(ファイルを添えるときは chat:file も) |
| 用途 | 複合タスクの自律実行・成果物生成 |
| 添えるファイル | 中身の部品(base64)だけ。URL の部品は使えません。1 ファイル 5 MB まで、5 ファイルまで、合計 20 MB まで。受け付けない種類のファイルは -32005(Content Type Not Supported) |
direct_llm
LLM に直接問い合わせを行います。agentMode: false 相当(プランニング・ツール利用なし)。数秒で答え、ファイルは返しません。
| 項目 | 内容 |
|---|---|
| 必要スコープ | a2a:all、または a2a:connect と chat:exec |
| 用途 | 知識ベース Q&A・翻訳・要約 等の単発処理 |
答えと成果物の読み方
- 最終回答は、
completedの状態のstatus.messageの文です。同じ文がresult-で始まる artifact にも入ります - ファイルは、ダウンロード用の URL を持つ artifact で届きます(下の「成果物の取得」)
- 質問は、
input-requiredの状態のstatus.messageの文です。同じ質問がinteraction-で始まる artifact にも入ります。そのmetadata.interactionTypeはchoice/confirmation/questionのいずれかで、質問の ID はmetadata.interactionIdに入ります(無い場合があります)。選択肢があるときはmetadata.options[]に入ります(choice以外では、選択肢がparts[0]の文の末尾にもOptions: …として入ります)。回答を待っているターンにはresult-artifact は付きません - 0.3 の
tasks/get・message/sendは、前のターンの artifact(前の質問のinteraction-など)も返します。どのターンの artifact かはartifact.metadata.messageId(ファイルの artifact では、artifactIdの末尾の<messageId>)で分けてください - 止めた・失敗したタスクは、状態(0.3 は
canceled・failed、1.0 はTASK_STATE_CANCELED・TASK_STATE_FAILED)で分かります。そのときの artifact は当てにしないでください。止めた・失敗したときに新しいresult-・interaction-が作られるとは限らず、前に送られたもの(質問待ちになったときのinteraction-など)や、取り直したときに作り直されたもの(質問のinteraction-、途中までの文のresult-)が残ることがあります ui-resource-で始まる artifact は人に見せる補助の UI です(下の「UI リソース」)。UI を返せないときは、その artifact ごと出しません
メッセージ構造
メッセージの形は A2A の規格どおりです。この製品では、次のように扱います。
messageId(メッセージごとに新しい値)とrole(0.3 は"user"、1.0 は"ROLE_USER")は必須です。0.3 で欠けると-32602です- 文の部品が要ります。文の部品が複数あるときは、改行でつないだ 1 つの指示として扱います
- データの部品(
data)は指示に使いません。文が空のメッセージ(ファイルだけ・データだけなど)は、タスクが失敗します - 実行の仕方は
metadataで指定します(下の「メタデータ」)
メタデータ
| キー | 既定値 | 説明 |
|---|---|---|
agentMode | true | true: エージェント実行 / false: LLM 直接問い合わせ |
agentLevel | "default" | default / high_performance |
reportMode | "with" | with: 実行の終わりに、整形した作業報告書(PDF)も作ります / without: その報告書だけを省きます(タスクの中身とほかに返すものは同じです) |
personaKey | (未適用) | ペルソナ(応答人格)の指定。未指定時はペルソナを適用しない。不明なキーは -32602(INVALID_PERSONA_KEY) |
optionIndex | (無し) | 選択肢から選んだ答えの番号(0〜9。最初が 0)。質問の ID(metadata.interactionId)のある質問を待つタスクの続きの返信だけに付けます(質問への答え方) |
いずれも省略可能で、0.3 と 1.0 で同じです。詳細は 接続方式ガイド - A2A 実行パラメータの指定 を参照してください。
成果物の取得
エージェントが生成したファイルは、artifact の ファイルの部品 として通知されます。artifact 自体にファイルの中身は含まれず、0.3 は file.uri、1.0 は url がダウンロード用の URL です。ファイルの名前は、0.3 は file.name、1.0 は filename に入ります。
ダウンロード用の URL はA2A と同じ Bearer トークンで GET します。a2a:all、または a2a:connect と chat:exec のトークンで、追加のスコープなしにダウンロードできます。
curl "<file.uri または url の値>" \
-H "Authorization: Bearer <access_token>" \
-o report.pdf
エンドポイントの詳細は ユーザー API リファレンス — 成果物取得 を参照してください。
UI リソース
エージェントが実行中に UI(グラフ・地図・カード一覧など)を生成した場合、artifactId が ui-resource- で始まる artifact として通知されます。
UI リソースは補助的な出力です。そのターンの実質的な出力は result- artifact(回答が質問で終わった場合は interaction- artifact)にあります。
実行中に生成された UI がすべて artifact になるとは限りません。HTML を提供できない場合、その ui-resource- artifact は配信されません。
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、または a2a:connect と chat:exec のトークンで、追加のスコープなしに取得できます。詳細は ユーザー API リファレンス — UI リソース取得 を参照してください。
type: "data" の場合はペイロードが parts[0].data.data にインラインで含まれるため、取得は不要です。
チャットで作った下書きのカードの ui-resource- artifact には、2 つ目の部品(データの部品)が付き、その data.draft(parts[1].data.draft)に下書きが入ります。形と作り方は ストリーミングガイド — delta.draft と同じです。
入力を求める UI(選択肢カードや質問フォーム)は ui-resource- ではなく interaction- で始まる artifact の 2 番目の部品(データの部品)に入ります。UI が提供できない場合はこの部品が付かず、parts[0] のテキストだけになります。回答の送り方は上の「質問への答え方」のとおりです。
取得した HTML をモデルのコンテキストに入れないでください(外部コンテンツではプロンプトインジェクションのリスクがあり、自社由来でも推論上の価値はありません)。取得した HTML は、アプリケーション側で人間に向けて描画するものです。
描画時の注意は ストリーミングガイド — 描画時の注意 を参照してください。
リクエスト例
SendMessage(1.0)
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: 1.0" \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "SendMessage",
"params": {
"message": {
"messageId": "9b2f0c1e-4d8a-4f7e-a1b2-3c4d5e6f7a8b",
"role": "ROLE_USER",
"parts": [{ "text": "売上データを分析してください" }],
"metadata": { "agentMode": true }
}
}
}'
応答の result.task.id がタスク ID、result.task.contextId が会話 ID です。
エラー
エラーの番号は A2A の規格どおりです(A2A 仕様)。エラーの文は、相手(人やエージェント)が次にすることが分かるように書いています。細かい印は、0.3 は error.data.code、1.0 は error.data[].metadata.code に入ります。
| 細かい印 | code | いつ |
|---|---|---|
MISSING_SCOPE | -32600 | 操作に必要なスコープが無い |
CONVERSATION_BUSY | -32600 | 同じ会話が実行中 |
ACCOUNT_SUSPENDED | -32600 | 管理者に利用を止められた利用者 |
FEATURE_NOT_PERMITTED | -32600 | 管理者が、エージェントモード(metadata.agentMode が true。省略したときも true)か、ファイルの添付を許可していない |
TEXT_SEGMENT_TOO_LARGE | -32600 | 文の部品が長すぎる |
PROJECT_CONVERSATION | -32600 | プロジェクトの実行の会話に送った |
CONVERSATION_ARCHIVED | -32600 | アーカイブ中の会話に送った(会話を元に戻してから送り直す) |
CONVERSATION_NOT_FOUND | -32600 | 0.3 で、無い・自分のものでない会話に送った |
CONTEXT_NOT_FOUND | -32602 | 1.0 で、無い・自分のものでない会話の contextId を送った |
CONTEXT_TASK_MISMATCH | -32602 | 1.0 で、taskId と contextId が合わない |
FILE_URI_NOT_SUPPORTED | -32602 | URL のファイルの部品を送った |
FILE_PROCESSING_FAILED | -32602 | 添えたファイルを受け付けられない(大きさ・数など) |
INVALID_PERSONA_KEY | -32602 | 不明な personaKey |
INVALID_OPTION_INDEX | -32602 | metadata.optionIndex が 0〜9 の整数ではない・質問の選択肢の外、または質問の ID のある質問を待つタスクの続きではない送信に付けた |
INVALID_PAGE_SIZE・INVALID_TIMESTAMP・INVALID_PAGE_TOKEN | -32602 | ListTasks のパラメータが不正 |
INVALID_PARAMS | -32602 | 1.0 の送信に message が無い |
EXECUTION_TIMEOUT | -32603 | 待つ送信が、実行の最大時間を超えた |
FEATURE_PERMISSIONS_UNAVAILABLE | -32603 | 機能の許可を確かめられない(時間をおいて送り直す) |
HTTP 層のエラー:
| HTTP Status | 説明 |
|---|---|
401 Unauthorized | アクセストークンが無効・期限切れ |
403 Forbidden | a2a:all も a2a:connect も無い、または /api/v1/a2a へのリクエストが前段のセキュリティの検査に止められた場合(error.code が waf_blocked) |
413 Payload Too Large | リクエストサイズが上限超過 |
503 Service Unavailable | 認証の仕組みが一時的に使えない。少し待ってから送り直してください。続くときは、サービスの管理者に問い合わせてください |
関連ドキュメント
- 接続方式ガイド - A2A — Agent Card 例とユースケース
- 認証 API リファレンス(SaaS) — トークン取得
- A2A 仕様 — プロトコル詳細