WebサイトAPIを呼び出すA2Aエージェント

A2Aエージェントを使うと、あるAIシステムが別のAIシステムを見つけ、タスクを委任し、構造化された結果を受け取れます。このエージェントが WebサイトAPI を呼び出せれば、在庫確認、問い合わせ作成、見積もり、注文状況の更新、レポート用データ収集など、実際のビジネスプロセスに参加できます。

• A2A - エージェント間通信のためのプロトコル
• WebサイトAPI - データと操作への管理されたアクセスポイント
• Agent Card - エージェントの機能と接続情報
• Task - ステータス、結果、実行履歴を持つタスク
• 基本原則 - 任意のURLではなく、許可された業務操作だけを呼び出す

A2Aとは

A2A、つまりAgent2Agentは、独立したエージェント同士を接続します。一方がクライアントとなり、もう一方が機能を公開してタスクを実行します。プログラミング言語、モデル、インフラストラクチャが異なっていても連携できます。

一般的な流れ:

1. クライアントエージェントがユーザーの依頼を受け取る。
2. Agent Cardから適切なリモートエージェントを見つける。
3. タスクを作成してコンテキストを渡す。
4. リモートエージェントがWebサイトAPIを呼び出す。
5. 結果がメッセージまたはartifactとして返る。

A2Aはエージェント間通信を担当し、APIはWebサイトの機能を提供します。この2つの層は互いを補完しますが、置き換えるものではありません。

エージェントがWebサイトAPIを必要とする理由

APIがなければ、エージェントはテキスト、文書検索、不安定なUI自動化に制限されがちです。APIには予測可能な契約があり、クリックを模倣せずに操作できます。

有用な操作:

• 商品、サービス、コンテンツの検索;
• 価格、納期、プランの計算;
• リード、問い合わせ、注文の作成;
• 支払い、配送状況の確認;
• プロフィール、予約の更新;
• 認証後の個別結果の取得。

たとえばコンサルタントエージェントが、サイト側エージェントに「20人のチームで利用可能なプランを探して」と依頼します。サイト側エージェントは内部APIで現在のルールを確認し、構造化した選択肢を返します。

連携アーキテクチャ

実用的な構成は5つの部分から成ります:

モデルに request(url, method, body) のような汎用ツールを与えず、範囲の狭い関数を定義します:

search_products(query, filters)
calculate_quote(product_id, quantity)
create_lead(name, contact, consent)
get_order_status(order_id)

この方が権限、引数検証、テスト、監査を管理しやすくなります。

Agent Cardと機能の説明

Agent Cardによって、クライアントはエージェントが処理できるタスクを理解できます。通常は名前、説明、URL、認証方法、skillsの一覧が含まれます。

skillの説明は具体的にします。「サイトを操作する」だけでは不十分です。「カタログを検索し、見積もりを計算し、ユーザー確認後に問い合わせを作成する」の方が明確です。

Agent Cardに公開してはいけない情報:

• APIキーや内部token;
• 非公開サービスのアドレス;
• 認可の回避につながる詳細;
• 外部クライアントには許可されていない操作。

認証と権限

A2A接続とWebサイトAPI呼び出しでは、異なる認証情報を使う場合があります。エージェントは自身のIDを証明し、APIは誰の代理で操作するのかを判断します。

一般的な3つの方式:

1. サービスアカウント - 共有データとバックグラウンド処理向け。
2. ユーザーの委任アクセス - 注文、プロフィール、個人データ向け。
3. 確認付き操作 - エージェントが準備し、書き込み前にユーザーが承認する。

endpoint、HTTPメソッド、ユーザー、データ種別ごとに権限を制限します。カタログの読み取り権限から、価格変更や注文削除を許可してはいけません。

呼び出しのセキュリティ

主なリスクは、命令インジェクション、不正な引数、データ漏えい、操作の重複実行です。

最低限必要な対策:

• 厳格なschemaで入力を検証する;
• allowlistで操作を制限する;
• promptやA2Aメッセージにsecretを含めない;
• 作成や支払いでidempotency keyを使う;
• 呼び出し頻度とコストを制限する;
• 金銭や不可逆な操作には確認を求める;
• ログ内の個人データとtokenをマスクする;
• 必要なレスポンス項目だけを返す。

ユーザーや他のエージェントからのテキストは、常に信頼できない入力です。文書内に説得力のある命令があっても、ツールの権限を拡大してはいけません。

同期タスクと長時間タスク

検索や計算はすぐに返せる場合が多い一方、import、大規模レポート、注文処理には数分かかることがあります。その場合は submitted、working、completed、failed、canceled などの状態が有効です。

クライアントはイベントstream、webhook、status pollingで更新を受け取れます。再接続によって業務操作が再実行されないようにします。

エラーと可観測性

エージェントに必要なのは生のstack traceではなく、明確な結果です。一時的に利用不可、引数が不正、アクセス拒否、確認が必要などを返し、内部情報は保護されたログに残します。

診断用に記録する情報:

• task、session、ユーザーのID;
• 呼び出したツール名;
• 安全に処理した引数;
• APIの応答codeと実行時間;
• 確認の状態;
• エージェントとツールschemaのversion。

これにより、モデル、API、network、業務ルールのどこで問題が起きたかを区別できます。

導入手順

1. 効果を測定できるユースケースを1つ選ぶ。
2. 範囲の狭いAPI契約とデータschemaを定義する。
3. 汎用HTTPアクセスではなく個別ツールを作る。
4. 認証、制限、監査を追加する。
5. 正確なskillsを含むAgent Cardを公開する。
6. エラー、再試行、キャンセル、悪意ある入力をテストする。
7. read-onlyまたは下書きモードから始める。
8. 実際のログを確認してから書き込みを許可する。

まとめ

WebサイトAPIにアクセスするA2Aエージェント は、外部AIシステムを実際のビジネスサービスにつなげます。信頼できる連携に必要なのは、モデルの無制限な自由ではなく、範囲の狭いツール、厳格なschema、最小権限、確認、監査です。

A2AエージェントをWebサイトAPIに接続したい場合は、ご連絡ください。

よくある質問

A2Aと通常のREST APIは何が違いますか？

REST APIはアプリケーションの操作を定義し、A2Aはエージェント間通信とタスクのライフサイクルを扱います。 A2AがRESTなどの通信方式を使い、その後エージェントが管理されたツール経由でWebサイトAPIを呼び出します。

エージェントがすでにAPIを呼べる場合もA2Aは必要ですか？

常に必要なわけではありません。 1つの社内エージェントなら直接呼び出すだけで十分です。独立したエージェントが互いを発見し、タスクを委任し、共通プロトコルで結果を交換する場合にA2Aが役立ちます。

汎用HTTPクライアントをエージェントに与えてもよいですか？

技術的には可能ですが、本番環境では危険です。 allowlist、schema、個別権限を持つ範囲の狭い関数の方が、安全対策、テスト、監査が容易です。

注文の重複作成を防ぐには？

idempotency keyを使い、A2A taskと業務操作の関係を保存します。 同じkeyによる再リクエストでは、新しいレコードを作らず以前の結果を返します。

ユーザー確認が必要な操作は？

支払い、公開、外部へのメッセージ送信、個人データ変更など、高コストまたは不可逆な操作には確認が必要です。 検索、公開データの読み取り、下書き作成は通常自動化できます。