byted-interactai-guide

InteractAI ガイド — 機能、セットアップ、接続、トラブルシューティングへの簡易ルーティング

これは外部向けの Skill 入口です。ユーザーの意図と実行段階を特定し、references/ 内の該当する専門知識を読み込みます。 API フィールド、設定の詳細、エラーコード、トラブルシューティングの全手順は references に記載されています。

トリガー条件

• 「会話できる音声エージェント／音声 Demo を作りたい」「火山 RTC 音声対話を動かしたい」など、接続に関する要望。
• 製品の対応状況、機能一覧、特定機能の仕組みや適用範囲についての質問。
• 現在対応しているモデル、インターフェースのバージョン、料金、公開テストの状況、最近追加された機能についての質問（最新の公式ドキュメントとの照合が必要）。
• 自然言語による StartVoiceChat / AibotCreate / AibotUpdate 設定の生成、変更、検証。
• 実行中に発生した「AI が回答しない」「Agent がルームに入らない」「ルームに入れるが音声が出ない」「字幕がない」などの障害。
• RTC / VoiceChat エラーコードの説明が必要な場合。

作業モードと CLI の利用可否

まず、ユーザーが必要としているのが相談か実際の実行かを区別します。この Skill の知識は単独で利用でき、自動化操作のみ CLI に依存します。

• 相談モード：ドキュメント／API の確認、概念の説明、接続方法の提案、ユーザーから提供されたログや現象に基づく手動トラブルシューティング。直接回答し、必要に応じて references/ を読み込みます。CLI がインストールされていないことだけを理由に、ユーザーへインストールを求めないでください。
• 実行モード：プロジェクトの作成、ログイン認証、App/Bot 設定の取得、Demo の起動、自動診断の実行、CLI によるオフラインのエラーコード照会。現在のタスクで初めて CLI を実行する前に、vertc version --format json を実行して利用可能か確認します。後続の各手順で確認を繰り返す必要はありません。

この Skill が実際に実行する vertc コマンドはすべて、実行ツールを呼び出す際にプロセスレベルの Skill 識別子を注入する必要があります。値は現在の SKILL.md frontmatter の name と version で構成し、@ を含めてはいけません。export、永続化、設定ファイルへの書き込みは行わないでください。これは内部呼び出しメタデータです。ユーザーに表示するコマンド、説明、最終回答には、このプレフィックスを含めないでください。

VE_SKILL_ID=<name>/<version> vertc <command>

コマンドが存在しない場合、または環境から vertc を見つけられない場合：

1. 現在の環境に CLI がインストールされていない、またはアクセスできないことを明確に伝え、そのため一時的に実行できない操作を説明します。
2. ドキュメントに関する相談、方法の検討、既存の証拠に基づく手動トラブルシューティングは引き続き可能であることも伝えます。Skill 全体が利用できないと判断したり、CLI の不足を RTC、VoiceChat、プロジェクトの障害と説明したりしないでください。
3. ユーザーが実際の実行を続けたい場合は、npm install -g @volcengine/rtc-cli を提示し、インストール後に vertc version --format json で確認するよう案内します。上位 Runtime が自動初期化を提供している場合は、上位スクリプトがインストールします。それ以外の環境では、事前にユーザーの同意を得る必要があります。

最短の実行可能な手順（公開コマンド）

vertc init --scene voice-agent --platform web --name my-agent
cd my-agent
vertc auth login
vertc dev

限られた候補からユーザーに選んでもらう必要がある場合、まず現在の環境で利用可能な構造化質問ツール（request_user_input や AskUserQuestion など）を使用し、ユーザーの選択を待ってから続行してください。利用可能な構造化質問ツールがない場合に限り、番号付きの簡潔なテキスト選択肢に切り替えてください。現在の環境で利用できないツールは呼び出さないでください。

• vertc auth login：認証が必要な場合は、まずブラウザーでのログインか手動ログインかを尋ねます。デフォルトでは、更新可能な Signin 認証情報を保護されたユーザーレベルのファイルに保存し、現在のプロジェクトは読み取りも変更もしません。Agent／非 TTY 環境では、ユーザーの同意を得てから明示的に --browser=open を使用する必要があります。ブラウザーが CLI の実行デバイスにない場合は、最初に vertc auth login --browser=manual --start を実行して、返された authorization_url をユーザーに渡します。ユーザーから認証コードを受け取った後、2 回目の実行でそのコードを stdin 経由で vertc auth login --resume に渡します。認証コードを受け取った後に --browser=manual や --start を再実行してはいけません。別の state が生成され、以前の認証コードは必ず失敗するためです。システムの認証情報ストレージにアクセスするのは、ユーザーが --store=keyring を選択した場合に限ります。
• vertc dev：RTC 設定がない場合、App が 1 つなら自動選択します。Bot がある場合はユーザーに選択してもらい、シーン JSON に書き込みます。Bot が 0 件であることを確認した後は、組み込みのデフォルト Scene を使用し、その後 Web と Server を一度に起動します。非 TTY 環境で vertc.dev.selection_required が返された場合は、error.details から公開候補のみを読み取り、--app-id または繰り返し指定可能な --bot-id を使って再実行します。Bot 候補が構造化質問ツールの選択肢上限を超える場合、候補を省略したりページ分けして表示したりしないでください。候補の総数を伝え、ユーザーが確認できるよう https://console.volcengine.com/conversational-ai/agentManage を案内したうえで、ユーザーから返された Bot 名または ID を error.details.bots から一意の Bot ID に解決します。名前が一意でない場合は、同名の候補だけを表示します。再選択が必要な場合は --reconfigure を使用します。 起動後、ページで Start をクリックしてルームに入り、対話を開始します。dev が利用可能な RTC アプリを検出できなかった場合は、ユーザーに https://console.volcengine.com/rtc?from=doc を開き、実名認証を完了して RTC サービスを有効にするよう直接案内します。
• 失敗した場合は、まず vertc doctor を実行して読み取り専用の診断を行い、その後、下のルーティング表に従って対応します。

意図／段階 → references のルーティング

ユーザーの意図／症状	実行段階	ルート
製品機能の概要／対応の有無／最新機能	相談	references/capabilities.md（変化の速い情報は、現在の公式ドキュメントで確認）
RTC ドキュメントの検索／本文の正確な確認	相談	references/topic-doc-catalog.md → documentation-retrieval.md（正確な list → fetch。ルートがない場合は search）
VoiceChat API フィールド／呼び出し方法	設定	references/voicechat-api.md（公式リンクを優先）
VoiceChat 設定の生成／変更／検証	設定	references/voice-agent-config.md → 必要に応じて model / validation / output を読み込み
ルーム参加の失敗／メディアなし／音声はあるが再生されない	ルーム参加・キャプチャ・公開・再生	references/web-sdk-diagnosis.md
Agent がルームに入らない／字幕がない／ASR・LLM・TTS の異常	StartVoiceChat の実行後	references/voice-agent-runtime.md
特定のイベントで証明できること／現在の証拠の範囲	簡易判定	references/integration-flow.md
「AI が回答しない」（症状が不明確）	全体フロー	references/integration-flow.md。原因を絞り込めない場合は integration-stages.md も読み込み
CLI コマンド自体のエラー	—	error.code と vertc doctor を確認

vertc skills read byted-interactai-guide/references/integration-flow.md を使うと、任意の reference を直接読み込めます。

設定に関する依頼では、まず voice-agent-config.md を読み、その後、そこから参照されている reference を読み込みます。フィールドの範囲、列挙値、Provider／Model／Resource の互換性は製品の変更に伴って変わるため、確定的な回答をする前に、現在の製品、インターフェース、API バージョンに対応する公式本文を確認する必要があります。コンソール設定の検証は、voice-agent-config-validation.md で定められた docs search → fetch のフローに従います。同じ区分では元の query を引き続き使用し、証拠が不十分な場合は unknown のままにします。

相談に現在の RTC ドキュメントが関わる場合は、まず references/documentation-retrieval.md に従って、公開されている読み取り専用コマンドで検索し、原文を取得します。検索の概要を本文として扱わないでください。サービスを利用できない場合に、古い情報へ黙って切り替えないでください。

機能に関する回答の範囲

次の項目を必ず区別します：製品で対応、モデル／バージョン／設定による制限あり、現在の Demo／CLI では未対応、未確認。 Demo に未実装であること、ローカルの reference に記載がないこと、ネットワークに接続できないことから、製品が非対応だと推論してはいけません。「非対応」と断定するには、現在の公式ドキュメントによる根拠が必要です。現在の機能、正確な API、モデルの互換性、料金、クォータ、公開テストの状況など変化の速い情報は、references/capabilities.md に従って、まず公式本文を確認します。確認できない場合は、ローカルの verified_at と未確認の範囲を説明します。

実行フェーズの識別

エンドツーエンドの流れ：認証 → Demo の設定 → Web SDK の初期化 → ユーザーのルーム参加 → マイク音声の収集と公開 → StartVoiceChat → Agent のルーム参加 → Agent によるユーザー音声のサブスクライブ → ASR/VAD → LLM → TTS → ユーザーによる Agent 音声のサブスクライブと再生。クイック判定の証拠については references/integration-flow.md を参照してください。全フェーズと詳細調査のルートについては references/integration-stages.md を参照してください。

「AI が回答しない」場合に一般的なチェックリストを提示しない

まず integration-flow.md を読み、前の手順が成功したことを確認してから次に進んでください。最初に失敗または証拠不足となったフェーズに到達した時点で停止します。クイック判定で絞り込めず、ユーザーが完全な原因特定を求めた場合に限り、integration-stages.md と関連する domain reference を 1 つ読みます。

診断ツール

• vertc doctor：読み取り専用の 2 段階チェック（CLI のセルフチェック + プロジェクトの準備状況）を行い、項目ごとに PASS/WARN/SKIP/UNKNOWN/FAIL を表示します。 認証情報の書き込み、設定の変更、ネットワーク経由でのプロジェクト情報の補完は行いません。ログイン状態は vertc auth login で修復し、 RTC App/Bot の設定がない場合は vertc dev または vertc dev --reconfigure を実行してください。
• vertc explain-error <code>：RTC/VoiceChat のエラーコードの意味と修正案をオフラインで照会し、domain（web-sdk/voice-agent）、source、verified の信頼性ステータスを出力します。VoiceChat の実行時エラーと OpenAPI の共通コードは、公式の「イベントとエラーコード」「共通エラーコード」と照合済み（verified）です。項目ごとの公開ソースがないログイン認証情報と署名のトラブルシューティング項目は curated-seed として示され、公式情報を確認するよう明示的に促します。確定した事実として扱わないでください。
• vertc docs search/fetch/list：RTC ドキュメントを読み取り専用で照会します。プロジェクトやログインは不要です。まず search で正確な results[].id を取得し、次に fetch で原文を確認してください。ディレクトリを閲覧する場合にのみ list を使用します。パラメーターのテンプレートと停止条件については references/documentation-retrieval.md を参照してください。

セキュリティ境界と注意事項

• AppKey などの秘密情報は環境変数のみを使用し、設定やログには絶対に書き込まないでください。ドキュメントやコマンドに実際の秘密情報を貼り付けないでください。
• vertc.dev.selection_required が発生した場合、または認証情報が不足している場合は、ユーザーに AppKey を求めたり、繰り返したり、記録したりすることを禁止します。error.details から公開 App/Bot ID を選択するようユーザーに案内してください。Bot がないことを確認した場合は、組み込みのデフォルト Scene を使用し、カスタマイズのため https://console.volcengine.com/conversational-ai/agentManage へのアクセスを案内できます。手動での代替手段として案内するのは、ローカルエディターまたは秘密情報管理のワークフローのみです。
• Voice Agent のエラー情報は、火山公式の「イベントとエラーコード」「共通エラーコード」と照合済みで、verified とされています。項目ごとの公開ソースがないログイン認証情報と署名のトラブルシューティング項目は curated-seed として示され、公式情報を確認するよう出力で明示的に促します。
• vertc --format json の成功または失敗の出力を読むたびに、トップレベルの _notice を確認してください。Runtime、CLI のインストール、バージョン、更新についてユーザーから質問があった場合は、_notice.update / _notice.skills と該当するコマンドを案内してください。製品に関する相談、設定、診断の場面では、これらのライフサイクル通知を無視してください。更新または同期には、引き続きユーザーの明示的な許可が必要です。
• ライフサイクル通知は 24 時間のローカルキャッシュから取得されるため、現在のタスクを中断したり、通常のコマンドに同期ネットワーク待機を追加したりしてはいけません。キャッシュがない状態での初回呼び出しでは通知が表示されず、バックグラウンドでの更新のみが開始される場合があります。これは最新版であることを意味しません。通知を待つためにポーリングや再試行を行わず、このタスクの後続の vertc JSON 出力を引き続き確認してください。制御された自動化では、それぞれ VERTC_NO_UPDATE_NOTIFIER=1、VERTC_NO_SKILLS_NOTIFIER=1 を設定できます。
• agent / env / token などは内部向け／legacy コマンド（デフォルトでは非表示）であり、デフォルトのクイックパスではありません。公開コマンドの init / auth login / dev / doctor / docs / explain-error / skills を優先してください。

権威ある情報源

• 製品の範囲：AI 音声・動画インタラクションソリューションの製品紹介
• 最新の変更：AI 音声・動画インタラクションソリューションのリリースノート
• ドキュメントツリー全体：AI 音声・動画インタラクションソリューション