メインコンテンツまでスキップ

A2A API リファレンス

AGENTIC STAR SaaS版が提供する A2A(Agent-to-Agent Protocol) エンドポイントの詳細仕様です。A2A は JSON-RPC 2.0 のインターフェースで、エージェント間の連携や独自フロントからのタスク実行に利用します。A2A の 0.3 と 1.0 の両方に対応しています。

Marketplace 版

このページは SaaS 版の A2A です。Marketplace 版の A2A は A2A API リファレンス(Marketplace 版) を参照してください。

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

ベース URL​

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

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

エンドポイント​

SaaS
メソッドエンドポイント説明
GET/.well-known/agent-card.jsonAgent Card 取得(スキル一覧・認証方式・ケイパビリティ)。トークンは要りません
POST/api/v1/a2aA2A 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.30.3
1.01.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:allA2A のすべての操作(ファイル添付と一覧を含む)
a2a:connectA2A のエンドポイントにつなぐ。操作ごとに、下の表のスコープも必要です

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.31.0形式説明
message/sendSendMessage待つ(JSON)メッセージを送信し、終わるか質問待ちになるまで待って結果を返します
message/streamSendStreamingMessageストリーミング(SSE)メッセージを送信し、SSE で逐次イベントを受信します
tasks/getGetTask待つ(JSON)タスクの状態を取得します
―ListTasks待つ(JSON)1 つの会話のタスクの一覧を取得します(1.0 だけ)
tasks/cancelCancelTask待つ(JSON)タスクを止めます
tasks/resubscribeSubscribeToTaskストリーミング(SSE)切れた後に、同じタスクのストリーミングにつなぎ直します

プッシュ通知の設定のメソッドは使えません(-32003)。

  • 待つ送信(message/send・SendMessage)は、終わるか質問待ちになるまで待ちます。0.3 の message/send は、configuration.blocking の値によらず待ちます
  • 1.0 の SendMessage で configuration.returnImmediately を true にすると、受け付けた時点のタスク(TASK_STATE_SUBMITTED)をすぐ返します。続きは GetTask か SubscribeToTask で追います

タスクの形​

タスクの範囲は版で違います。

0.31.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 は読みません。

taskIdcontextId対象の依頼(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 で指定します(下の「メタデータ」)

メタデータ​

キー既定値説明
agentModetruetrue: エージェント実行 / 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
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 をモデルのコンテキストに入れないでください(外部コンテンツではプロンプトインジェクションのリスクがあり、自社由来でも推論上の価値はありません)。取得した HTML は、アプリケーション側で人間に向けて描画するものです。

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

リクエスト例​

SendMessage(1.0)​

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: 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-326000.3 で、無い・自分のものでない会話に送った
CONTEXT_NOT_FOUND-326021.0 で、無い・自分のものでない会話の contextId を送った
CONTEXT_TASK_MISMATCH-326021.0 で、taskId と contextId が合わない
FILE_URI_NOT_SUPPORTED-32602URL のファイルの部品を送った
FILE_PROCESSING_FAILED-32602添えたファイルを受け付けられない(大きさ・数など)
INVALID_PERSONA_KEY-32602不明な personaKey
INVALID_OPTION_INDEX-32602metadata.optionIndex が 0〜9 の整数ではない・質問の選択肢の外、または質問の ID のある質問を待つタスクの続きではない送信に付けた
INVALID_PAGE_SIZE・INVALID_TIMESTAMP・INVALID_PAGE_TOKEN-32602ListTasks のパラメータが不正
INVALID_PARAMS-326021.0 の送信に message が無い
EXECUTION_TIMEOUT-32603待つ送信が、実行の最大時間を超えた
FEATURE_PERMISSIONS_UNAVAILABLE-32603機能の許可を確かめられない(時間をおいて送り直す)

HTTP 層のエラー:

HTTP Status説明
401 Unauthorizedアクセストークンが無効・期限切れ
403 Forbiddena2a:all も a2a:connect も無い、または /api/v1/a2a へのリクエストが前段のセキュリティの検査に止められた場合(error.code が waf_blocked)
413 Payload Too Largeリクエストサイズが上限超過
503 Service Unavailable認証の仕組みが一時的に使えない。少し待ってから送り直してください。続くときは、サービスの管理者に問い合わせてください

関連ドキュメント​