building-livekit-agents

LiveKit エージェントの構築

このスキルでは、音声エージェントの構成方法を説明します。API の詳細は含まれていません。API は変更されるため、reading-livekit-docs で確認してください。

推奨される方法である LiveKit Cloud を前提としています。マネージドインフラストラクチャに加え、モデルには LiveKit Inference を使用するため、プロバイダーごとの API キーを管理する必要はありません。

エージェントを実行する場所と、プロジェクトが使用する LiveKit は別の問題です。ユーザーがセルフホストするエージェント（LiveKit Cloud のエージェントホスティングではなく、自身のサーバーで実行するエージェント）も、LiveKit Cloud に接続し、LiveKit Inference を使用できます。Inference は LiveKit Cloud の機能なので、利用できないのはプロジェクトが LiveKit OSS で実行される場合だけです。アーキテクチャに関する助言はどちらの場合にも当てはまります。LiveKit OSS では、各プロバイダー独自のプラグインと API キーを使ってモデルを利用します。

コードを書く前に

1. reading-livekit-docs を読み込み、これから使う API を調べてください。記憶に頼って LiveKit のコードを書かないでください。
2. プロジェクトが LiveKit Cloud プロジェクト（または LiveKit OSS サーバー）に接続されていることを確認してください。LIVEKIT_URL、LIVEKIT_API_KEY、LIVEKIT_API_SECRET は通常 .env に設定されています。CLI で設定できます。
3. 最初のエージェントクラスを書く前に、ワークフローの構成を決めてください（下記の「構成」を参照）。後からモノリスをハンドオフ方式に分割するより、最初から 2 つのエージェントで始めるほうが手間を抑えられます。
4. 検証方法を計画してください。 debugging-livekit-agents（実際の会話を行う）、testing-livekit-agents（ターンを検証する）、またはその両方を使うか、今の段階で決めてください。コードの分割方法に影響するためです。

音声によって要件が変わる点

音声エージェントは、話者を付けただけのチャットエージェントではありません。次の制約が、設計上の判断の大半を左右します。

レイテンシ。 ユーザーは数百ミリ秒以内の応答を期待します。コンテキストのサイズ、ツールの数、ツール呼び出しがクリティカルパス上にあるかどうか、応答をストリーミングするかどうかは、いずれもレイテンシの予算を消費したり、節約したりします。ネットワークの停滞やプロバイダーのタイムアウトも想定してください。これらは日常的に発生します。

コンテキストサイズ。 どのモデルでも、ツール定義が 50 個ある 10,000 トークンのシステムプロンプトは動作が遅く感じられます。モデルはターンごとにそのすべてを読み直すためです。各フェーズには、そのフェーズから使えるツールと必要な指示だけを与えてください。

傾聴。 ユーザーは内容をざっと読んだり、前に戻って確認したりできず、エージェントの発話中に話し始めることもあります。長い返答は問題であり、無音は故障のように感じられ、中断は当たり前に起こります。

構成：ハンドオフとタスク

よくある失敗は、何でもこなす単一のエージェントです。すべてのツール、指示、状態を抱え込んで動作が遅く不安定になり、その時点で分割しようとすると、全面的な書き直しになります。

ハンドオフでは、あるエージェントから別のエージェントへ制御を移します。挨拶 → 要件の聞き取り → 解決、または一般サポート → 請求専門担当者のように、会話の自然な区切りに配置してください。そうすれば、各エージェントが自分のツールと指示だけを持つようになります。次のエージェントにコンテキストを要約して渡せる区切りを選んでください。次のエージェントが前のエージェントと同じ情報をすべて必要とするなら、その区切りは適切な位置ではありません。

タスクは、1 つの成果を目的とする、対象を厳密に絞ったプロンプトです。完全なエージェントを必要としない個別の処理や、一般的なプロンプトよりも焦点を絞ったプロンプトが適している場合に使います。

エージェントの責任を 1 文で説明できないなら、分割してください。

ツール

• ツールの説明が動作を左右します。 エージェントが誤ったツールを呼び出したり、呼び出すタイミングを誤ったりした場合は、モデルのせいにする前に説明を確認してください。最もよくある原因は、そのツールをいつ使うべきかが説明に書かれていないことです。
• 可能な限り、ツールをクリティカルパスから外してください。 ユーザーは、待たされるツール呼び出しのたびにレイテンシを感じます。
• ツールの失敗に備えてください。 バックエンドが停止している場合や何も返さない場合に、エージェントがどう応答するかを決めてください。ツールの失敗時に答えをでっち上げるエージェントは、後から問題を見つけるのが非常に困難です。

モデルが解釈し、状態はコードが管理します

モデルは会話を読み取り、アクションを提案します。記録、権限チェック、状態遷移、外部へのあらゆる作用は、アプリケーションコードが管理します。「デモでは動くのに本番環境では失敗する」エージェントの多くは、どこかでこの境界が曖昧になっています。

• コードで意図を分類してはいけません。 承認、拒否、訂正、キャンセル、「次の火曜日」などは、ランタイムモデルが解釈します。正規表現、キーワード一覧、フレーズのホワイトリストは、テストしないような形で誤判定します。「保守的な」二つ目のゲートとして追加しても、同じ欠陥があります。コードでは 構造（型付きの日付、列挙型、必須フィールド）を検証し、意味はモデルに任せてください。
• ツール呼び出しはモデルによる解釈であり、それが正しかったことの証明ではありません。 メッセージの出所、バージョンチェック、順序、ビジネスルールは、検証可能なコード内で管理してください。
• ツールが返すのは事実であり、文章ではありません。 コンパクトなデータ、結果、実行可能なエラーを返し、表現はモデルに任せてください。タスクで逐語的な開示が求められる場合に限り、正確な文面をスクリプトにしてください。
• フォームではなく、ユーザーに合わせてください。 呼び出し元がまとめて伝えた事実は受け入れ、不足または曖昧な点だけを尋ねてください。明確な回答の後に「確認するには「はい」と言ってください」のような決まり文句を決して要求しないでください。
• セッションごとに、権威ある状態オブジェクトを一つだけ持ち、モデルが提示した事実は、信頼できる本人確認情報、時計、ID、受領記録と分けて管理してください。

変更一つにつき、意味も一つだけにする

エージェントのバグで最も高くつくのは、呼び出し元の意図より多く、または少なく状態を変更することです。「彼のメモは不要」がリスト全体を消去する、訂正によって確認済みフィールドもリセットされる、値を言い直しただけなのに承認が無効になる、といったケースです。状態を変更するツールを書く前に、対象、変更内容、変更せずに残すものを明確にしてください。そのうえで、異なる処理をすべき最も近いリクエストと組み合わせてください。

要点は次のとおりです。省略は状態を維持します。不足、空、未知、クリア済みは、それぞれ異なる状態です。コレクションにはアプリケーションが発行したIDを付与します。適用前に検証します。対象を限定した否定によってコレクション全体をクリアしてはいけません。値に変更がなければ、何もしません。処理の実行前に確認が必要なタスクでは、承認はそのバージョンに対する 後続の実際のユーザーメッセージであり、配信は発話の境界で追跡し、成功を公開するのは書き込みがコミットされた後に限ります。クローズ、出力の所有権、テキスト入力と音声入力で異なるフック経路を通る仕組みを含む詳細は、references/state-and-effects.mdに記載されています。予約、編集、確認、通話終了を行うものを構築する前に読んでください。

完全な経路を通る失敗テストから始める

ツールの範囲を広げたり、ペルソナを磨いたりする前に、一般的なユーザーの目標を一つ選び、実際のエージェントを通して必要な処理まで実行してください。予約が作成される、記録が変更される、通話が終了する、といった結果です。期待される結果は、アプリケーション独自のエクスポートではなく、ユーザーのリクエストに基づいて記述してください。続けて、拒否すべき最初のガードもテストしてください。あらゆるものを拒否するテストでは、ガードについて何も証明できません。ほかのものを追加する間も、このテストの組み合わせを成功状態に保ってください。

完了と判断する前に検証する

プロンプトの変更もコードの変更と同じくらい簡単にエージェントの動作を壊します。一度手動で試すだけでは、検証したことになりません。

• 構築中は、 debugging-livekit-agentsを使って会話を実行してください。エージェントをローカルで動かし、テキストまたは音声でターンを送信でき、各返信の背後で行われたツール呼び出しを確認できます。
• 完了と判断する前に、 testing-livekit-agentsを使ってテストを書いてください。最低限、ユーザーが求めた中核的な動作、ツールがある場合は正しい引数でのツール呼び出し、失敗経路を一つカバーしてください。
• 稼働中のエージェントに変更を適用する前に、 writing-livekit-scenariosとrunning-livekit-simulationsを使ってシミュレーションを実行してください。

ユーザーがテスト不要と求めた場合は、テストなしで構築し、本番環境に移行する前にはテストを推奨することを一度だけ伝えて、そのまま進めてください。

よくある間違い

• 「とりあえず」1つのエージェントから始める。 最初に構造を決めることになりますが、実装自体はシンプルなままにできます。
• レイテンシへの対処を先延ばしにする。 レイテンシは積み重なり、修正のコストも増す一方です。
• 理解していないサンプルをコピーする。 サンプルが示すのは1つのパターンです。そのまま丸ごと貼り付けると、説明できない余分なコンテキストやコンポーネントまで取り込んでしまいます。
• モデルに関する知識が最新だと思い込む。 最新ではありません。reading-livekit-docs を参照してください。
• 手動テストだけでリリースする。 プロンプトの編集で、目に見えるエラーがないまま動作が変わることがあります。テストを行えば、ユーザーより先に気づけます。

関連スキル

• 事実、API、変更履歴：reading-livekit-docs
• 構築しながらライブ会話を進める：debugging-livekit-agents
• ターン単位のテスト：testing-livekit-agents
• 会話全体のテスト：writing-livekit-scenarios、running-livekit-simulations
• 状態、承認、コミット、配信、終了：references/state-and-effects.md
• 本番環境へのデプロイと健全な状態の維持：operating-livekit-agents