コンテンツにスキップ
ファウンダー価格 — 早期顧客向けに固定今すぐ始める →

エージェントハンドオフパターン：AIエージェント間のタスクルーティング

エージェントハンドオフパターンとは、あるAIエージェントがタスク、蓄積されたコンテキスト、実行権限を別のエージェントに転送するプロトコルです。どのデータが境界を越えるか、何が破棄されるか、そして認証情報がタスクとともに転送されるかどうかを決定します。ほとんどのハンドオフ失敗はルーティング失敗ではなく、下流エージェントが静かに失敗したり、侵害されたエージェントが機密ペイロードデータを窃取したりするときにのみ表面化するコンテキスト損失または認証情報漏洩の失敗です。

エージェントハンドオフパターンとは、自律型AIエージェントがタスクをピアまたはスペシャリストエージェントに委任する方法を管理するソフトウェア設計パターンです。コンテキスト転送のデータ契約、タスク配信のルーティングメカニズム、エージェント間での認証情報またはコンテキストの漏洩を防ぐ分離保証を指定します。

4つの標準的なハンドオフパターン

プッシュハンドオフ：呼び出し元が呼び出し先を直接起動する

プッシュハンドオフでは、呼び出しエージェントがタスクコンテキストを含むペイロードを構築し、受信エージェントに直接通知します。通常、関数呼び出し、メッセージ送信、または呼び出し先を起動するAPIの呼び出しによって行われます。呼び出し元は、呼び出し先が受け取るデータ、受け取るタイミング、タスクを処理するエージェントを正確に制御します。

プッシュハンドオフは、OpenAI Agents SDKのhandoff()プリミティブ（GitHubスター27,133、MIT）が使用するパターンです。呼び出し元は転送前にコンテキストフィールドを削除または変換するinput_filter関数をオプションで渡せます。input_filterなしでは、蓄積された機密コンテンツを含む完全なコンテキストウィンドウが呼び出し先に渡されます。

強み：低レイテンシ、タスクルーティングの直接制御、オブザーバビリティツールでのトレースが容易。
リスク：呼び出し元が認証情報と機密コンテキストを明示的に削除する必要がある；呼び出し元と呼び出し先の密結合により、スペシャリストエージェントの追加または削除時にルーティングロジックの変更が必要。

プルディスパッチ：呼び出し先が共有キューから取得する

プルディスパッチでは、呼び出しエージェントが特定のエージェントに直接通知せずに、タスクを共有キューまたは受信ボックスに書き込みます。呼び出されるエージェントはキューを監視し、自分の能力に合ったタスクを要求します。これによりワーカープール全体での負荷分散が可能になり、呼び出し元をどの特定エージェントが作業を処理するかの知識から切り離します。

プルディスパッチは認証情報の公開を減らします：キューメッセージにはタスクの説明と出力キーポインタのみが含まれ、呼び出し元の完全なコンテキストは含まれません。

強み：水平スケーリング、疎結合、同一ワーカー間の自然な負荷分散。
リスク：負荷下でキューの深さが無制限に増加する可能性；タスク順序保証はキューセマンティクスに依存；オブザーバビリティには複数のキュー読み取りにわたるタスクIDの相関が必要。

ブラックボードルーティング：ポインタベースのコンテキスト分離

ブラックボードポインタハンドオフでは、呼び出し元が共有永続ストアの名前付きキー（例：output/researcher/task_abc123）に出力を書き込み、呼び出し先にキー名のみを送信します。呼び出し先はキーを読み取り、必要なフィールドを正確に取得します。生の認証情報、中間スクラッチパードコンテンツ、呼び出し元の完全なコンテキストはハンドオフメッセージに決して現れません。

OpenLegionのhand_off()関数はこのパターンをネイティブに実装しています：ブラックボードのoutput/{agent_id}/{handoff_id}に出力データを書き込み、受信者の受信ボックスにそのキーへのポインタを含むタスクエントリを作成し、受信者を起動します。Vaultに格納された認証情報はメッシュによって実行時に注入されます。

強み：最高の認証情報分離、呼び出し先は必要なものだけを読み取る、キーバージョン履歴による完全な監査証跡、切り離されたタイミング。
リスク：直接プッシュと比較して読み取り操作が追加される；適切なアクセス制御を持つ信頼性の高い共有ストアが必要。

ストリーミングハンドオフ：インクリメンタルコンテキスト転送

ストリーミングハンドオフでは、完全な出力を待つのではなく、呼び出しエージェントが生成するにつれてトークンごとまたはチャンクごとにコンテキストが転送されます。これによりリアルタイムパイプラインでのエンドツーエンドレイテンシが最小化されます。

ストリーミングハンドオフは認証情報公開の最大リスクを持ちます：呼び出し元がフィルタリングする前に推論の途中で生成された機密コンテンツがストリームに含まれる可能性があります。

強み：最低のエンドツーエンドレイテンシ、リアルタイムマルチエージェントコラボレーション。
リスク：最もセキュリティ確保が難しく、最も複雑に観察され、呼び出し先が部分的なコンテキストを適切に処理する必要がある。

OpenLegionの見解：コンテキスト損失と認証情報漏洩が本当のハンドオフバグである理由

ほとんどのマルチエージェントハンドオフ失敗は2つのカテゴリに分類されます：コンテキスト損失バグと認証情報漏洩バグ。どちらも設計によって防止できます。

コンテキスト損失の数値：LLMコンテキスト圧縮の評価では、ハンドオフ境界での単純な切り捨てが、構造化された要約と比較してマルチホップ推論タスクのタスク完了率を低下させることが一貫して示されています。解決策はより大きなコンテキストウィンドウではなく、完了した作業、残りの作業、主要な発見のための明示的なフィールドを持つ構造化されたハンドオフペイロードです。

認証情報漏洩：OWASP LLM06:2025（機密情報の開示）は、エージェント間メッセージパッシングによる認証情報の窃取をトップ10のLLM脆弱性として明示的にカバーしています。

コンテキスト損失問題：境界で何が破棄されるか

コンテキスト損失の根本原因は、呼び出しエージェントが知っていることとハンドオフペイロードが伝達することとの不一致です。構造化されたハンドオフペイロードはこれを防ぎます：呼び出し元はフィールドを明示的に入力します：タスク目標、これまでの完了した作業、未解決のサブタスク、主要な発見、出力キーポインタ。

ハンドオフペイロードによる認証情報の窃取（OWASP LLM06:2025）

Google ADKのtransfer_to_agent()は、会話履歴を含む完全なSessionオブジェクトを受信エージェントに渡し、デフォルトで最大32Kトークンのコンテキスト転送を作成します。いずれかのフレームワークを使用しているチームは、ハンドオフ実装をAIエージェントセキュリティ：認証情報の分離とプロンプトインジェクション防御と照合して監査する必要があります。

セキュアなデフォルトとしてのブラックボードポインタパターン

ブラックボードポインタパターンは、アプリケーション層のフィルタリングに依存するのではなく、プロトコル層で認証情報の公開を排除します。OpenLegionのVaultに格納された認証情報はエージェントコンテキストに注入されることはありません。

主要フレームワークがハンドオフを実装する方法

OpenAI Agents SDK：input_filterを使用したhandoff()（27,133スター）

openai/openai-agents-python（GitHubスター27,133、MITライセンス）はhandoff()をプッシュパターンとして実装しています。input_filterパラメータはv0.0.5（2025年3月）に追加され、明示的なオプトインが必要です。

from agents import Agent, handoff, RunContextWrapper

def strip_credentials(ctx: RunContextWrapper, input_data: ResearchInput) -> ResearchInput:
    return ResearchInput(task=input_data.task, context=input_data.context)

researcher = Agent(
    name="researcher",
    handoffs=[handoff(writer_agent, input_filter=strip_credentials)]
)

Google ADK：transfer_to_agent()とSessionオブジェクト転送（20,100スター）

google/adk-python（GitHubスター20,100、Apache-2.0）はtransfer_to_agent()によるハンドオフを実装しており、会話履歴を含む完全なSessionオブジェクトを渡します。受信エージェントはすべてを受け取り、不要な履歴を明示的に破棄する必要があります。

LangGraph：共有型付き状態を使用したCommand(goto=)

LangGraph（langchain-ai/langgraph、Apache-2.0）はCommand(goto='ノード名')とオプションの状態更新によるエージェントルーティングを実装しています。状態はグラフ内のすべてのノード間で共有される型付き辞書です。LangGraphの共有状態モデルはノード間の認証情報分離を提供しません。

from langgraph.types import Command

def researcher_node(state: AgentState) -> Command:
    result = researcher.invoke(state)
    return Command(
        goto="writer",
        update={"research_output": result, "completed_steps": state["completed_steps"] + ["research"]}
    )

OpenLegion：ブラックボードポインタと受信ボックス配信を使用したhand_off()

OpenLegionのhand_off()関数はブラックボードポインタハンドオフをネイティブに実装しています。

hand_off(
    to="writer",
    summary="調査完了：langchain-alternative、2847語のソース資料",
    data='{"topic": "langchain-alternative", "sources_key": "research/langchain-alt-sources", "word_count_target": 3000}'
)

ハンドオフデータ契約

含めるもの：タスクサマリー、出力キー、関連履歴

適切に設計されたハンドオフペイロードは構造化された仕様であり、トランスクリプトのダンプではありません。含めるもの：

  • タスクサマリー（200語以内）：呼び出し先が達成する必要があること
  • 出力キーポインタ：呼び出し元の出力が格納されているブラックボードキー
  • 完了した作業のサマリー：すでに行われたこと、会話としてではなく事実として述べる
  • 未解決のサブタスク：呼び出し先が責任を負う特定の項目
  • 構造化パラメータ：呼び出し先のタスクが必要とする型付き入力

除外するもの：生の認証情報、完全なコンテキストウィンドウ、中間スクラッチパッド

ハンドオフペイロードから除外するもの：

  • APIキー、トークン、認証情報：実行時にメッシュによって注入されるべき
  • 完全な会話トランスクリプト：関連するサマリーに切り詰める
  • 中間推論スクラッチパッド：呼び出し元の思考プロセスは呼び出し先に有用ではない
  • 呼び出し先の役割が必要としないデータ：コンテキストにも最小権限を適用する

ハンドオフルーティングメカニズム

静的ルーティング：ハードコードされたエージェントID

静的ルーティングは特定のタイプの各ハンドオフを特定の名前付きエージェントに送信します。実装が簡単でトレースが容易。ターゲットエージェントが利用不能、過負荷、または交換された場合に壊れます。

動的ルーティング：LLMで選択されたスペシャリスト

動的ルーティングはLLM呼び出しを使用して、タスクの特性に基づいて適切なスペシャリストエージェントを選択します。柔軟性を提供しますが、レイテンシを追加し、LLMがタスクを誤分類するとルーティングエラーの可能性があります。

条件付きルーティング：ルールベースのエスカレーション

条件付きルーティングは確定的なルールを適用してターゲットエージェントを選択します。LLMベースのルーティングよりも予測可能ですが、すべてのルーティング条件に対して明示的なルール定義が必要です。

フォールバックとタイムアウト処理

各ハンドオフは、タイムアウトウィンドウ内に呼び出し先が応答しない場合の対処法を定義する必要があります。オプション：

  • 同じ呼び出し先での再試行：失敗が一時的である可能性が高い場合に適切
  • 代替エージェントへの再ルーティング：プライマリ呼び出し先が継続的に利用不能な場合に適切
  • オペレーターへのエスカレーション：タスクが人間の判断を必要とする場合に適切
  • ブラックボードへの失敗の書き込みと継続：ダウンストリームタスクがオプションの場合に適切

ハンドオフパターンのセキュリティと信頼性の比較

ディメンションプッシュハンドオフプルディスパッチブラックボードルーティングストリーミングハンドオフ
ルーティングメカニズム呼び出し先への直接起動呼び出し共有キュー/受信ボックス要求キー書き込み+呼び出し先ウォッチインクリメンタルトークンストリーム
コンテキスト分離呼び出し元がペイロードを制御；input_filter必須キューメッセージのみ最高：呼び出し先は名前付きキーのみを読み取る最低：完全なコンテキストが境界を越える
認証情報公開リスク中：input_filterオプトインに依存低：キューはタスクポインタのみを保持非常に低：認証情報はペイロードに決してない高：ストリームに機密コンテキストが含まれる可能性
オブザーバビリティハンドオフごとの単一トレースイベントキューの深さ+クレームイベントキーバージョン履歴+受信ボックスイベントトークンレベルのトレーシングが必要
レイテンシ最低低（キュー読み取りオーバーヘッド）低（ブラックボード読み取りオーバーヘッド）最低のエンドツーエンド（ストリーミング）
最適な用途密結合されたスペシャリスト委任負荷分散されたワーカープール非同期疎結合パイプラインリアルタイムコラボレーション

よくある質問

エージェントハンドオフパターンとは何ですか？

エージェントハンドオフパターンとは、あるAIエージェントから別のエージェントにタスクを転送するためのプロトコルです。どのコンテキストデータが境界を越えるか、受信エージェントへの通知方法、認証情報またはメモリの漏洩を防ぐための分離保証を指定します。4つの標準的なパターンはプッシュハンドオフ、プルディスパッチ、ブラックボードポインタルーティング、ストリーミングハンドオフで、それぞれ異なるセキュリティ、レイテンシ、オブザーバビリティのトレードオフを持ちます。

OpenAI Agents SDKはハンドオフをどのように実装しますか？

OpenAI Agents SDK（GitHubスター27,133、MIT）はhandoff()をプッシュパターンとして実装しています。呼び出しエージェントはターゲットエージェントとオプションのinput_filter関数でhandoff()を呼び出し、転送前にコンテキストからフィールドを削除します。input_filterパラメータはv0.0.5（2025年3月）に追加され、明示的なオプトインが必要です；なしでは完全なコンテキストウィンドウが呼び出し先に渡されます。

Google ADKはエージェントハンドオフをどのように実装しますか？

Google ADK（GitHubスター20,100、Apache-2.0）はtransfer_to_agent()を使用し、会話履歴を含む完全なSessionオブジェクトを受信エージェントに渡します。これによりデフォルトで最大32Kトークンのコンテキスト転送が作成されます。受信エージェントは完全な履歴を受け取り、不要な以前のコンテキストを明示的に破棄する必要があります。

ブラックボードポインタハンドオフパターンとは何ですか？なぜより安全なのですか？

ブラックボードポインタハンドオフでは、呼び出し元が共有ストア（output/agent-id/task-idなど）の名前付きキーに出力を書き込み、呼び出し先にデータ自体ではなくキーポインタのみを送信します。呼び出し先は必要なフィールドのみを読み取ります。認証情報はハンドオフメッセージに決して現れず、OWASP LLM06:2025（機密情報の開示）の窃取ベクターを排除します。OpenLegionのhand_off()はこのパターンをネイティブに実装しています。

エージェントハンドオフにはどのようなセキュリティリスクがありますか？

主なリスクは認証情報の窃取です：ハンドオフ中に渡されるコンテキストオブジェクトに環境変数、ベアラートークン、またはAPIキーを含めるフレームワークは、それらを受信エージェントに公開します。受信エージェントは侵害されているか、より広いネットワークアクセスを持っている可能性があります。OWASP LLM06:2025はこれをトップ10のLLM脆弱性として識別しています。二次的なリスクはコンテキストポイズニングです。

ハンドオフの失敗とタイムアウトをどのように処理しますか？

堅牢なハンドオフパイプラインはタイムアウトとフォールバックパスを定義します：同じ呼び出し先で再試行、代替スペシャリストへの再ルーティング、人間のオペレーターへのエスカレーション、またはブラックボードへの失敗記録の書き込み。呼び出しエージェントはハンドオフIDを追跡し、タスク完了イベントを監視する必要があります。

ハンドオフペイロードにはどのデータを含めるべきですか？

含めるもの：簡潔なタスクサマリー（200語未満）、共有ストアの出力データキーへのポインタ、完了した作業の事実、未解決のサブタスク、呼び出し先の役割が必要とする構造化パラメータ。除外するもの：生のAPI認証情報、完全な会話トランスクリプト、中間推論スクラッチパッド、呼び出し先の役割が必要としないデータ。

OpenLegionでの安全なエージェントハンドオフ

ハンドオフ境界はほとんどのマルチエージェント信頼性問題の起点です。コンテキスト損失は下流タスクの品質を低下させ、ペイロード内の認証情報漏洩はパイプライン長とともに増大する窃取リスクを生み出します。

OpenLegionのブラックボードポインタハンドオフはプロトコル層で両方の問題に対処します。hand_off()は出力を名前付きキーに書き込み、受信者の受信ボックスにポインタのみを配信し、Vaultプロキシによる認証情報注入に依存します。受信者はブラックボードから必要なものだけを読み取り、それ以上は読み取りません。

ハンドオフプロトコルが見逃す失敗を検出する監視層については、エージェントオブザーバビリティ：パイプラインステージ全体のハンドオフのトレースを参照してください。どのハンドオフパターンを選択するかを決定するフレームワーク層については、本番展開のためのAIエージェントフレームワークの比較を参照してください。

OpenLegionで安全なマルチエージェントパイプラインを構築する →