voice-agents

ボイスエージェント

概要

クライアントの発見、フィードバック、チェックインの通話に対応する ElevenLabs Conversational AI のボイスエージェントを作成します。クライアントのコンテキストに基づいて、エージェントの設定を自動生成します。

クイック判断ツリー

What type of agent?
│
├── Discovery agent (interview clients)
│   └── --scope discovery
│
├── Feedback agent (post-project)
│   └── --scope feedback
│
├── Check-in agent (relationship)
│   └── --scope check-in
│
├── Qualification agent (leads)
│   └── --scope qualification
│
└── Onboarding agent (new contacts)
    └── --scope onboarding

環境のセットアップ

# Required in .env
ELEVENLABS_API_KEY=your_api_key
OPENROUTER_API_KEY=your_api_key  # For prompt generation

一般的な使い方

ディスカバリーエージェントの作成

python scripts/create_voice_agent.py "Microsoft" --scope discovery --notes "CRM migration project"

フィードバックエージェントの作成

python scripts/create_voice_agent.py "Acme Corp" --scope feedback --notes "Post-project review"

ドライラン（プレビュー）

python scripts/create_voice_agent.py "Test Company" --scope discovery --notes "Testing" --dry-run

スコープの種類

スコープ	目的
discovery	クライアントチームに業務、課題、技術スタックについて聞き取ります
feedback	完了したプロジェクトについてフィードバックを集めます
check-in	定期的に関係を確認します
qualification	営業前にインバウンドリードの適格性を確認します
onboarding	新しい連絡先から情報を集めるためのガイドをします

生成されるエージェント設定

スクリプトは以下を生成します。

エージェント名

[{Company Name}] {Scope} Agent v1

最初のメッセージ

音声に最適化された挨拶で、以下の内容を含みます。

• Casper Studios を代表して電話していることを伝えます
• 適切な相手と話しているかを確認します
• スコープに沿った目的を伝えます
• 所要時間の目安（10～15分）を伝えます
• 了承を求めます

システムプロンプト

以下を含む包括的な会話ガイドです。

• アイデンティティとコンテキスト
• トーンとコミュニケーションスタイル
• 会話の流れ（5～7段階）
• インタビューのテクニック
• ガードレールと境界

出力

{
  "agent_id": "abc123xyz",
  "agent_name": "[Microsoft] Discovery Agent v1",
  "agent_url": "https://elevenlabs.io/app/conversational-ai/agents/abc123xyz",
  "first_message": "Hi there! This is an AI assistant...",
  "company_name": "Microsoft",
  "scope": "discovery"
}

コンテキストの補完

スクリプトはオプションで Google Drive からコンテキストを取得します。

1. クライアントの「Research」ドキュメント
2. 以前のミーティングの文字起こし（初回通話）

利用できない場合は、提供されたメモのみを使って生成します。

費用

サービス	費用
OpenRouter（プロンプト生成）	約 $0.01～0.03
ElevenLabs エージェントの作成	無料
Google Drive	無料

セキュリティに関する注意事項

認証情報の取り扱い

• ELEVENLABS_API_KEY を .env ファイルに保存します（Git に絶対にコミットしないでください）
• OPENROUTER_API_KEY を .env ファイルに保存します（Git に絶対にコミットしないでください）
• 漏えいした場合は、各ダッシュボードからキーを再生成します
• スクリプトの出力に API キーを記録または表示しないでください

データプライバシー

• ボイスエージェントは顧客とリアルタイムで会話します
• 通話内容には機密性の高い業務上の議論が含まれる場合があります
• エージェントのプロンプトには社内の業務コンテキストが含まれる場合があります
• 会話ログは ElevenLabs に保存されます
• Google Drive から取得したクライアントのコンテキストがプロンプトに含まれる場合があります

アクセス範囲

• ELEVENLABS_API_KEY - ボイスエージェントの作成と管理へのフルアクセス
• OPENROUTER_API_KEY - プロンプト生成に使用する AI モデルへのアクセス
• Google OAuth - オプション。クライアントのコンテキスト補完に使用

コンプライアンスに関する考慮事項

• 録音への同意：会話が録音される場合があることを通話相手に知らせてください
• AI であることの開示：通話相手が AI エージェントと話していることを開示してください
• 通話相手のプライバシー：会話データは ElevenLabs のサーバーで処理されます
• GDPR：EU 域内の通話相手との会話には、適切な同意が必要です
• TCPA/CCPA：適用される電気通信関連の規制を遵守してください
• 通話録音に関する法律：録音に関する法律は管轄区域によって異なります（片方の当事者の同意か、両方の当事者の同意か）
• データ保持：ElevenLabs のデータ保持ポリシーを確認してください
• エージェントのガードレール：エージェントに適切な会話の境界が設定されていることを確認してください

トラブルシューティング

よくある問題

問題：エージェントの作成に失敗する

症状： ボイスエージェントの作成時に API エラーが発生する 原因： 設定が無効、必須フィールドが不足、または API の問題 解決策：

• エージェント設定の JSON 形式を検証します
• すべての必須フィールド（name、first_message、system_prompt）が指定されていることを確認します
• プロンプトの長さが上限を超えていないことを確認します
• 要件について ElevenLabs API のドキュメントを確認します

問題：無効な音声 ID

症状： 「Voice not found」または「invalid voice_id」エラーが発生する 原因： 音声 ID が存在しないか、アクセスできない 解決策：

• ライブラリにある有効な ElevenLabs 音声 ID を使用します
• https://elevenlabs.io/app/voice-library で音声を利用できるか確認します
• 音声が別のアカウントのカスタム音声ではないことを確認します
• カスタム音声を利用できない場合は、デフォルトの音声を使用します

問題：API クォータを超過しました

症状：「Quota exceeded」またはレート制限エラーが発生する **原因：**ElevenLabs のサブスクリプション上限に達しています 解決策：

• https://elevenlabs.io/app/subscription で使用状況を確認します
• より多くの容量を利用できるサブスクリプションプランにアップグレードします
• 同時に実行するエージェントの数を減らします
• 使用していないエージェントを削除して、空き枠を確保します

問題：通話中にエージェントが応答しない

**症状：**エージェントは作成されますが、会話中に応答しません **原因：**システムプロンプトの問題、Webhook の設定、またはサービスの問題です 解決策：

• まず ElevenLabs コンソールでエージェントを直接テストします
• システムプロンプトを確認し、指示が明確であることを確かめます
• Webhook URL にアクセスできることを確認します（設定している場合）
• ElevenLabs のサービス状況を確認します

問題：OpenRouter のプロンプト生成に失敗する

**症状：**エージェントプロンプトの生成中にエラーが発生する **原因：**OpenRouter API の問題、または無効なモデルです 解決策：

• OPENROUTER_API_KEY が正しく設定されていることを確認します
• OpenRouter でモデルが利用可能か確認します
• 現在のモデルが利用できない場合は、別のモデルを試します
• --dry-run を指定して、API を呼び出さずにテストします

問題：Google Drive のコンテキストが読み込まれない

**症状：**クライアントのコンテキストなしでエージェントが作成される **原因：**OAuth の問題、またはクライアントフォルダーが見つかりません 解決策：

• Google OAuth の認証情報を確認します（google-workspace スキルを参照）
• クライアントフォルダーが想定される場所にあることを確認します
• 代替手段として --notes フラグでコンテキストを指定します
• まずコンテキストの拡充を行わずに実行して、問題を切り分けます

リソース

• references/elevenlabs.md - ElevenLabs API の詳細

統合パターン

コンテキストを考慮したエージェント

スキル： transcript-search → voice-agents ユースケース： クライアントの履歴を踏まえた音声エージェントの作成 フロー：

1. transcript-search で過去のクライアントとの会議を検索します
2. 関係の履歴、課題、好みを抽出します
3. パーソナライズされた会話のため、音声エージェントのシステムプロンプトにコンテキストを含めます

エージェントのメモを CRM に記録

スキル： voice-agents → attio-crm ユースケース： 音声エージェントの通話概要を記録する フロー：

1. 音声エージェントがヒアリングまたはフィードバックの通話を完了します
2. 通話の概要、インサイト、アクションアイテムを抽出します
3. 通話の詳細を記載したメモを Attio の会社レコードに作成します

調査結果を反映したエージェント

スキル： parallel-research → voice-agents ユースケース： 企業情報を音声エージェントに提供する フロー：

1. 対象企業について parallel-research を実行します
2. 最近のニュース、資金調達、技術スタック、課題を抽出します
3. 情報に基づいた会話のため、調査結果をエージェントのプロンプトに含めます