debugging-livekit-agents

LiveKit エージェントをライブでデバッグする

lk agent debugger は、ユーザーのエージェントをバックグラウンドプロセスとしてローカルで実行し、会話を一度に 1 ターンずつ進められるようにします。コーディングエージェント向けに作られており、ユーザー役を演じ、直前の返答をもとに次の発話を選び、その間にエージェントが行ったことを確認できます。

デフォルトではセッションはテキストモードです。音声はオフで、LiveKit ルームにも何も送信されないため、各ターンをすばやく進められます。音声経路にバグがある場合は、代わりに音声モードでセッションを開始してください（音声モードを参照）。

初めて使用する前に、コマンドが存在することを確認し、ヘルプを読んでください。

lk agent debugger --help

ヘルプには詳しい説明があり、サブコマンドとフラグについての正式な情報源となるため、このスキルではそれらを再掲しません。コマンドが見つからない場合は、インストールされている CLI がこの機能より古いものです。その場合はユーザーに lk を更新するよう伝え、それまでは testing-livekit-agents を使用してください。古いコマンドの形式を推測しないでください。

一連の手順

エージェントを起動し、ユーザーのターンを発話させ、何が起きたかを確認し、コードを編集して再起動し、これを繰り返して、終わったら停止します。おおよその流れは次のとおりです。

lk agent debugger start
lk agent debugger say "Hi, what can you do?"
lk agent debugger say "Book me a table for two tonight"
lk agent debugger stop

各 say は、エージェントが応答で行ったすべての内容（引数と結果を含むツール呼び出し、ハンドオフ、エラー）に続いて、返答を出力します。ターンの合間には、エージェントのチャット履歴、ライブイベントストリーム、プロセスログ、ステータスを確認できます。サブコマンドは --help に記載されています。

コードを編集したら、必ず再起動してください。 実行中のセッションは古いコードを保持するため、すでにファイルに存在しない動作のデバッグに時間を費やしがちです。

使ったデバッグ方法

• 返答だけでなく、ツール呼び出しも確認してください。 返答から何がうまくいかなかったかがわかり、ツール呼び出しとその引数からは、通常その理由がわかります。引数が間違っているなら、プロンプトまたはツールの説明に原因があります。呼び出し自体がない場合は、通常、ツールの説明に使用タイミングが記載されていません。
• ツールの動作に問題がある場合は、ログをターンに合わせて表示してください。 オプションを有効にすると、該当するターンの下にエージェントのログ行が表示されます。そのため、ツールのトレースバックが、ユーザーに聞こえたはずのサニタイズ済みエラーのすぐ下に表示されます。症状から原因を特定する最短の方法です。
• 会話の記憶に頼らず、エージェントのチャット履歴を確認してください。 履歴には、指示やツールの変更を含め、LLM が確認した内容が記録されます。動作があり得ないように見える場合は、想定していたコンテキストと実際のコンテキストが異なることが、通常は履歴からわかります。
• 修正する前に再現し、同じターンを再実行してください。 バグを引き起こした say の行を順序どおりに残し、修正前と修正後を比較できるようにします。
• 会話全体を進めてください。 早い段階で集めた情報が失われる、フローの途中でユーザーが考えを変える、ハンドオフでコンテキストが失われるなど、多くのバグは複数のターンを経て初めて明らかになります。1 ターンだけでは見つけられません。
• プログラムがターンを決める場合は、スクリプト化してください。 機械可読な出力と、意味のある終了コードが用意されています。フィールド名を推測せず、現在の形式を --help で確認してください。

音声モード

テキストモードでは STT と TTS が省略されるため、別のつづりとして聞き取られた名前、STT が単語として書き起こした数字、ターンが早く終わりすぎる問題、音声入力のみを受け付けるリアルタイムモデルからの内容は確認できません。CLI が対応している場合は、音声を使ってセッションを開始すると（start --help を確認してください）、各 say が LiveKit Inference TTS によってエージェントのマイク入力に送られ、エージェントは音声パイプライン全体を実行します。

• 症状が聞き取りに関する場合、またはテキストモードで実行できない音声対話モデルをエージェントが使っている場合に使用してください。ロジック、プロンプト、ツールの不具合にはテキストモードを使ってください。テキストモードのほうが速く、書き起こしのノイズに邪魔されません。
• LiveKit Cloud プロジェクトが必要です。 音声のターンは LiveKit Inference で実行されるため、lk にプロジェクトの認証情報が必要です。テキストモードでは必要ありません。
• 聞き取られた内容と送信した内容を比較してください。 各ターンには、送信した文と単語が異なる場合、エージェントがその文をどう書き起こしたかが表示されます。この違いが不具合の全容であることもよくあります。エージェントは、実際に聞き取った内容に対して正しく応答していたのです。
• 話し手が実際に口にするような文を書いてください。 音声入力の処理をエージェントがどう行うかテストする場合は、数字やコードを単語で書き、どちらの形式も受け付ける必要がある場合は、両方をテストしてください。
• モードはセッションごとに設定されます。 再起動してもモードは維持されます。モードを切り替えるには、停止してから再度開始してください。
• 無音が長く続くと、ターンが早く終わることがあります。 エージェントが応答し、しばらく静かな状態が続くとターンは終了します。エージェントが応答を終える前に長く間を置く場合（たとえば、リアルタイムモデルが委任した応答を待っている場合）、残りの応答は次のターンに表示されます。エージェントが応答しなかったと結論づける前に、チャット履歴を確認してください。

音声モードでは、応答中のエージェントに割り込んだり、エージェントの声の様子を確認したりすることはできません。その場合は lk agent console または音声シミュレーションを使用してください。

別の方法を使う場合

状況	使用するもの
実際に聞いてみたい、またはユーザーに試してもらうものを用意したい	lk agent console（マイクとスピーカーを使用し、人がキーボードを操作）
同じ失敗が繰り返し発生する	ターン単位のリグレッションテスト（testing-livekit-agents）
会話全体の結果を大規模に評価したい	シミュレーション（running-livekit-simulations）
調査中のターンの書き起こしまたはエンドポインティング	音声モードのデバッガー（上記）
多くの会話にわたる割り込みや音声動作を評価したい	音声シミュレーション（running-livekit-simulations）

デバッガーは、対話的に不具合を見つけるためのものです。不具合を見つけたら、後の変更で気づかないうちに再発しないよう、テストを作成してください。

関連スキル

• エージェントの構築：building-livekit-agents
• 見つかった不具合をテストとして固定：testing-livekit-agents
• 会話全体のチェック：writing-livekit-scenarios、running-livekit-simulations
• 本番環境のみで発生する不具合（ワーカープロセス、プロバイダー、シャットダウン）：operating-livekit-agents
• CLI フラグと API の情報：reading-livekit-docs