Koei's Digital Garden

Agents and handoffs

6 min read

Agents and handoffs

参照元: LiveKit Agents Documentation ロードマップ: 学習ロードマップ

What（何についてか）

本ドキュメントは、LiveKit Agentsにおけるマルチエージェント構成の実装方針を扱う。中心テーマは、Agentを責務ごとに分割し、handoffで制御を移譲することで、会話フローを明示的に設計することである。

Agent Sessionは会話全体の実行基盤であり、アクティブなAgentが現在の会話制御を担う。必要に応じて別Agentへ制御を渡し、セッションレベルの共有状態（userdata）で業務状態を継続する。

Why（なぜ必要か）

単一Agentで全要件を処理すると、役割・権限・モデル特性が混在し、推論の一貫性と保守性が低下する。特に、権限境界（例: 決済APIアクセス）と会話フェーズ（例: 受付→実処理）を分離しない場合、誤操作や過剰コンテキストによる品質劣化が発生しやすい。

このため、Agent分割とhandoff戦略、state共有、context preservationを別々に設計することが重要になる。

How（どう動くか）

Agent分割とhandoff

Agentは、指示・利用可能Tool・推論方針のセットとして定義する。初期AgentはAgentSessionで指定し、会話中に以下の方法で切替える。

  • 明示切替: update_agent（Python）
  • 自動切替: Toolの戻り値として別Agentを返す

handoff発生時はセッション履歴に AgentHandoff(old_agent_id, new_agent_id) が記録され、制御移譲のトレースが可能になる。

graph LR
    S["AgentSession"] --> A1["IntakeAgent"]
    A1 -->|"tool return"| H["AgentHandoff"]
    H --> A2["BillingAgent"]
    A2 --> SH["session.history に handoff記録"]

Passing state（userdata）

session.userdata はセッション内の共有データ領域である。意味としては「状態そのもの」より「状態を保持するための構造化データ置き場」に近い。

ただし、検証済みフラグやintentの更新のように時系列で値が変化するため、結果としてセッションはstatefulに振る舞う。実装上は dataclass が推奨されるが、要件に応じて Pydantic BaseModel も採用可能である。

型パラメータの整合

AgentSession[T] と RunContext[T] は同一Tを使うのが通常設計である。これにより ctx.session.userdata を型安全に参照できる。

session.userdata と ctx.session.userdata は同一セッションの共有領域を参照する想定で利用する。

Chat history と context preservation

履歴は2層で扱う。

  1. session.history: セッション全体のイベント履歴（handoff記録を含む）
  2. chat_ctx: 各Agent/TaskのLLM推論に実際に投入する文脈

新しいAgent/Taskはデフォルトでfreshな文脈で開始しうる。過去会話を引き継ぐ場合は chat_ctx を明示設定する。

graph TD
    H["session.history\n(監査ログ)"] -->|"参照"| D["デバッグ・追跡"]
    C["chat_ctx\n(推論入力)"] -->|"投入"| L["LLM"]
    P["context preservation設計"] --> C

context preservationの運用は次の3択で設計する。

  • Full継承: 既存chat_ctxをそのまま引継ぐ（実装容易だがノイズ増加）
  • Fresh開始: 文脈を引継がない（安全だが再質問増加）
  • Slim継承: 必要情報のみ再構成して渡す（実務上の第一候補）

Key Concepts

用語説明
Agent会話制御の中核。指示・Tool・推論方針を持つ長寿命ユニット。
Active Agent現在セッション制御を握っているAgent。
Handoff会話制御を別Agentへ移す操作。
session.userdataセッション共有の構造化データ領域。
RunContext[T]Tool実行時コンテキスト。session.userdata に型付きアクセス可能。
session.historyセッション全体のイベント履歴。handoff記録の監査に使用。
chat_ctx各Agent/TaskのLLM入力文脈。引継ぎは明示設計する。

設計上の判断基準

Agentの分割基準は、役割差・モデル差・権限差・会話フェーズ差の4軸で判断する。権限境界がある場合は必ずAgent分離し、handoff条件を明文化する。

state共有は session.userdata に寄せ、推論用文脈は chat_ctx に限定する。会話品質と安全性を両立するには、context preservationを「全渡し」ではなく「必要最小限の再構成」として設計する。

一言まとめ

Agents and handoffsの本質は、会話制御の責務分離と制御移譲の明示化である。userdata で状態を継続し、chat_ctx を選択的に引き継ぐことで、複雑な音声AIワークフローを安全かつ保守可能に実装できる。

Graph View

Backlinks