メインコンテンツへスキップ
エージェントは入力イベントを処理し、出力イベントを yield して会話を制御します。

エージェントとは

エージェントは入出力イベントループを制御します。process メソッドはイベント(ユーザーの発話、通話開始など)を受け取り、レスポンスを yield します。 エージェントには次の 2 つの形式があります:
  1. process メソッドを持つ クラス
  2. 同じシグネチャ (env, event) -> AsyncIterable[OutputEvent] を持つ 関数
エージェントの仕組み:
  • イベントが到着(ユーザーの発話、通話開始、ボタン押下)
  • SDK が agent.process(env, event) を呼び出す
  • エージェントが出力イベント(発話、ツール呼び出し、ハンドオフ)を yield する
  • SDK が音声、LLM 呼び出し、状態管理を担当

LlmAgent

LiteLLM を介して 100 以上の LLM プロバイダーをラップする組み込みの LlmAgent を使用します:

プロンプト

system_prompt でエージェントのパーソナリティを定義し、introduction で挨拶を指定します:

サポートされているモデル

LlmConfig オプション

履歴管理

LlmAgent は、LLM が参照する会話履歴を構造化された形で制御するための history 属性を公開しています。 エントリの追加:
履歴セグメントの置換:

ターンごとのオーバーライド

process() はキーワード引数を受け付け、エージェントを変更せずにそのターンだけに適用します:
明示的に設定された LlmConfig のフィールドのみが反映され、未設定のフィールドはエージェントに保存されている設定にフォールスルーします。 ツールを永続的に変更する場合(例:特定時点以降に end_call を有効化)、ターンごとのオーバーライドではなく agent.tools を直接変更してください。

会話ループの制御

イベントフィルター を使用して、エージェントの process メソッドが実行されるタイミング、そしてそれを中断できるイベントを制御します。

デフォルトの動作

つまり、エージェントは通話開始時に挨拶し、ユーザーが発話を終えると応答し、ユーザーから割り込まれることができます。

フィルターのカスタマイズ

デフォルトを上書きするには get_agent からタプルを返します:

よくあるカスタマイズ

応答性を高める(部分的な書き起こしを処理):
これによりエージェントは、ユーザーの発話が終わる前に処理を開始するため、よりレスポンシブな体験を実現できます。 割り込み不可能なターン: 特定のメッセージをユーザーに中断されずに完了させたい場合は、AgentSendText で送信するときに出力を interruptible=False としてマークします。
関数を使ったカスタムロジック:
ガードレール、ルーティング、エージェントラッパーなどの高度なパターンについては 高度なパターン を参照してください。

着信通話の処理

通話が着信すると、発信者情報を確認したり、エージェントが起動する前に応答方法を設定したりできます。
  1. Web クライアントまたはテレフォニープロバイダーから通話が着信
  2. pre_call_handler が発信者の詳細を含む CallRequest を受け取る
  3. 構成(ボイス、言語)を返すか、通話を拒否する
  4. get_agent 関数が、強化されたリクエストを使ってエージェントを作成

CallRequest の解析

着信通話に関する情報が含まれます: agent フィールドには次の項目を持つ AgentConfig が含まれます:

PreCallResult を返す

エージェントが起動する前に、pre_call_handler でボイスや言語を設定するか、通話を拒否します:
クライアントアプリケーションは、コールリクエストでメタデータ(ユーザー ID、言語設定、アカウントティアなど)を渡せます。pre_call_handler はこれを読み取り、それに応じて TTS/STT を構成します。

構成オプション

TTS オプション: STT オプション:

通話の拒否

None を返して、403 ステータスで通話を拒否します:

カスタム発音

特定の単語の発音方法を制御するには 発音辞書 を使用します:

エージェントロジックで通話メタデータにアクセスする

CallRequestget_agent で利用できます:
LlmConfig.from_call_request() は優先順位を自動的に処理します:
  1. CallRequest.agent.system_prompt の値(設定されている場合)
  2. ユーザーが指定したフォールバック値(指定されている場合)
  3. SDK のデフォルト
CallRequest を使うと、プレイグラウンドからシステムプロンプトを瞬時にイテレーションでき、コード側では技術的な構成とフォールバックのデフォルトを担当できます。

ユーザーに先に話させる

ユーザーが先に話すのを待つには、introduction を空文字列に設定します:

カスタムエージェント関数

高度なユースケースでは、エージェントを関数としてゼロから構築できます:

カスタムエージェントクラス

または、状態を持つクラスとしても構築できます:
ほとんどの開発者は、カスタムエージェントをゼロから構築するのではなく、LlmAgent をツールと組み合わせて使うのがおすすめです。カスタムエージェントは、LLM の推論なしでイベント処理ロジックを完全に制御したい場合に強力です。