> ## Documentation Index > Fetch the complete documentation index at: https://docs.oneinbox.ai/llms.txt > Use this file to discover all available pages before exploring further. # エージェント > エージェントは発信者が話す音声 AI です — 個性、声、取れるアクションを持ちます。 ## エージェントとは エージェントは完全な音声ペルソナです。名前だけで作成すると、すぐに使用できます — OneInbox がデフォルトの LLM、デフォルトの声、デフォルトのシステムプロンプトを自動的に設定します。カスタマイズしたい場合のみ変更が必要です。 | コンポーネント | デフォルト | 変更するタイミング | | --------------- | ----------------- | ----------------------------------- | | **LLM**（AI の頭脳） | 汎用システムプロンプトで自動作成 | 特定のペルソナ、スクリプト、温度が必要な場合 | | **ボイス** | デフォルトの声があらかじめ設定済み | ElevenLabs または Cartesia の特定の声が必要な場合 | | **システムプロンプト** | 汎用アシスタント | 特定の指示やスクリプトに従わせたい場合 | | **言語** | `en` | 別の言語で文字起こしを行う必要がある場合 | | **ツール** | なし | エージェントにアクションを取らせたい場合（SMS、転送、データ取得） | 1 つのエージェントがブラウザ通話（Web SDK 経由）と直接の電話通話（アウトバウンドおよびインバウンドの両方）を処理します — 通話タイプごとに別のエージェントは不要です。 *** ## エージェントを作成する 2 つの方法があります — デフォルトで作成して後でカスタマイズするか、最初から独自の設定を提供するかです。どちらも完全に動作するエージェントを作成します。 ### オプション A — デフォルトで作成 名前だけで OK。OneInbox がデフォルトの LLM、声、システムプロンプトを自動的に作成します。レスポンスの `llm_id` と `agent_id` を使って後でカスタマイズできます。 ```bash theme={null} curl -X POST https://api.oneinbox.ai/v1/agents \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Support Agent" }' ``` ```json theme={null} { "id": "agt_abc123", "name": "Acme Support Agent", "llm_id": "llm_xyz789", "created_at": "2026-06-01T10:00:00Z" } ``` ### オプション B — 独自の設定で作成 最初から設定したいフィールドを渡します。`name` 以外のフィールドはすべて任意です。 ```bash theme={null} curl -X POST https://api.oneinbox.ai/v1/agents \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Support Agent", "language": "en", "first_message": "Hi! Thanks for reaching out to Acme. How can I help you today?", "tts": { "provider": "elevenlabs", "voice_id": "" }, "silence_timeout_seconds": 10, "max_duration_seconds": 600, "interruption_sensitivity": 0.6, "enable_recording": true, "voicemail_detection": true, "voicemail_message": "Hi, please leave a message and we'll call you back." }' ``` レスポンスの `llm_id` は自動作成された AI モデルです。使用したオプションに関わらず、システムプロンプトの設定、ツールの紐付け、ナレッジベースのリンクに使用します。 エージェントはすぐに使用できます。電話番号不要でブラウザ通話でテストできます — 完全にインターネット経由で動作します（[Web SDK](/concepts/web-sdk) と同じ仕組み）： ```bash theme={null} curl -X POST https://api.oneinbox.ai/v1/calls/web \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "agent_id": "agt_abc123" }' ``` *** ## デフォルトをカスタマイズする デフォルトでは汎用のシステムプロンプト、デフォルトの声、デフォルトの LLM で動作します。エージェントに特定の個性やスクリプトを与えるには、作成レスポンスの `llm_id` を使って LLM モデルを更新します： ```bash theme={null} curl -X PATCH https://api.oneinbox.ai/v1/models/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "system_prompt": "You are a helpful sales rep for Acme Corp. Your goal is to qualify leads and book product demos. Keep all replies under two sentences. Be warm and direct.", "temperature": 0.7 }' ``` 変更は新しい通話にすぐに適用されます。1 つの LLM モデルで複数のエージェントを動かすことができます — エージェント間で頭脳を共有するには、`{ "llm_id": "llm_xyz789" }` でエージェントを PATCH します。モデルを一度更新すれば、それを使用するすべてのエージェントに変更が反映されます。 セルフホストまたはサードパーティの LLM を使用するには、`provider` を `"custom"` に設定し、`custom_websocket_url` を指定します。URL は `wss://`、`ws://`、`https://`、または `http://` が使用できます — サーバーは OpenAI 互換のストリーミングチャット補完インターフェースを公開している必要があります。 ```bash theme={null} curl -X POST https://api.oneinbox.ai/v1/models \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "セルフホスト LLM", "provider": "custom", "custom_websocket_url": "wss://your-llm-server.example.com/v1/chat/completions", "system_prompt": "You are a helpful voice assistant.", "temperature": 0.7 }' ``` *** ## 利用可能なモデルを確認する カタログには LLM、STT、TTS プロバイダーの受け入れ可能なモデル ID が一覧表示されます — エージェントや LLM にカスタムモデルを設定する前に確認できます。 ```bash theme={null} # LLM プロバイダー — openai, anthropic, groq curl "https://api.oneinbox.ai/v1/models/catalogue?provider=openai" \ -H "Authorization: Bearer " # STT プロバイダー — deepgram, assembly_ai curl "https://api.oneinbox.ai/v1/models/catalogue?provider=deepgram" \ -H "Authorization: Bearer " # TTS プロバイダー — cartesia, elevenlabs, openai curl "https://api.oneinbox.ai/v1/models/catalogue?provider=cartesia" \ -H "Authorization: Bearer " ``` 各アイテムの `source` フィールドは `live`（プロバイダーから直接取得）、`seed`（クレデンシャルなしで表示される静的リスト）、または `unverified` です。 *** ## エージェントにツールを与える ツール（SMS 送信、発信者データの取得、通話転送、会議予約など）は、エージェントではなく **LLM モデル** に紐付けられます。 **理由:** LLM モデルが会話中に何をするかを決定します。ツールはそれが取れるアクションです — だからそこに置かれます。そのモデルを使用するすべてのエージェントは、すべてのツールを自動的に継承します。 ツールを追加するには、まず作成し、エージェントの `llm_id` に紐付けます： ```bash theme={null} # 1. ツールを作成（例：発信者情報を取得） curl -X POST https://api.oneinbox.ai/v1/tools \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "capture_lead_info", "type": "extract_information", "description": "Extract the caller name, budget, and timeline from the conversation.", "extraction_schema": { "fields": [ { "name": "caller_name", "type": "string", "description": "Full name of the caller" }, { "name": "budget", "type": "string", "description": "Budget the caller mentioned" }, { "name": "timeline", "type": "string", "description": "Their decision timeline" } ] } }' # 返却されたツールの "id" を保存 # 2. エージェントの LLM モデルに紐付け curl -X PATCH https://api.oneinbox.ai/v1/models/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "tool_ids": [""] }' ``` → [ツールガイド](/guides/tools) — 7 種類すべてのツールタイプと詳細な例 *** ## 音声認識（STT） STT は発信者の音声を LLM が理解できるテキストに変換します。エージェントの `transcriber` オブジェクトを設定してプロバイダーとモデルを選択します。 以下の STT プロバイダーはすべてプラットフォーム提供です — 認証情報は不要です。 | プロバイダー | モデル | 最適な用途 | | -------------- | -------------------------------------- | -------------------------------- | | **Deepgram** | `nova-3`（デフォルト）、`flux-en`、`flux-multi` | 低遅延・高精度。`nova-3` がほとんどのユースケースに推奨 | | **Whisper** | `whisper-1` | 幅広い言語対応 | | **AssemblyAI** | `best`、`nano`、`slam-1` | 複雑な音声環境での高精度 | | **Azure** | 例：`en-US-JennyNeural` | エンタープライズ Azure 環境 | ```bash theme={null} curl -X PATCH https://api.oneinbox.ai/v1/agents/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "transcriber": { "provider": "deepgram", "model": "nova-3", "language": "ja" } }' ``` 発信者の言語に合わせて `language` を設定します — 例：日本語は `"ja"`、ヒンディー語は `"hi"`。言語が不明な多言語通話には `flux-multi` を使用します。 *** ## 音声合成（TTS） TTS はエージェントのテキスト返答を音声に変換します。エージェントの `tts` オブジェクトを設定してプロバイダー、ボイス、速度を選択します。 以下の TTS プロバイダーはすべてプラットフォーム提供です — 認証情報は不要です。 | プロバイダー | 主なボイス | 最適な用途 | | -------------- | ------------------------- | -------------- | | **Cartesia** | Sarah、Liam、Barbershop Man | 超低遅延・自然なプロソディ | | **Deepgram** | Thalia、Asteria、Zeus | 高速・会話的 | | **ElevenLabs** | Roger、Laura、Alice | 高い表現力・感情表現 | | **OpenAI** | Alloy、Echo、Nova、Shimmer | 安定した品質・高負荷時も安定 | | **Minimax** | Female Phone、Male Phone | 電話品質の音声に最適化 | | **Shisa** | JA Female | 日本語特化 | ```bash theme={null} curl -X PATCH https://api.oneinbox.ai/v1/agents/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "tts": { "provider": "cartesia", "voice_id": "", "speed": 1.0, "stability": 0.5 } }' ``` `voice_id` には `/v1/voices` エンドポイントの `vc_...` ID を使用してください — プロバイダーのネイティブ ID ではありません。利用可能なボイス ID の全リストは [ボイス](/jp/guides/voices) を参照してください。 | フィールド | 範囲 | 役割 | | ----------- | ------- | ---------------------------------------- | | `voice_id` | — | `/v1/voices` の OneInbox ボイス ID（`vc_...`） | | `speed` | 0.5〜2.0 | 再生速度。`1.0` が通常の発話速度 | | `stability` | 0.0〜1.0 | ボイスの一貫性。高いほど安定したトーン、低いほど表現豊か | *** ## 主要なエージェントフィールド | フィールド | デフォルト | 制御内容 | | -------------------------- | ------- | ------------------------------------------------------------------------------ | | `first_message` | — | 通話が接続したときにエージェントが最初に言うこと。2 文以内に収める | | `language` | `en` | 文字起こし言語。エージェントレベルで設定 — `{ "language": "ar" }` | | `silence_timeout_seconds` | `10` | 通話が終了するまでの無音の秒数 | | `max_duration_seconds` | `600` | 通話時間のハードキャップ。範囲：30〜7200 | | `interruption_sensitivity` | `0.5` | 発信者が割り込みやすさ（0.0 = 難しい、1.0 = とても簡単） | | `responsiveness` | `0.5` | 発信者が話し終わった後にエージェントが応答する速さ（0 = ゆっくり、1 = 素早い） | | `enable_recording` | `false` | 通話終了後に通話レコードで `recording_url` を取得するには `true` に設定 | | `voicemail_detection` | `false` | アウトバウンド通話でボイスメールの挨拶を検出 | | `voicemail_message` | — | ボイスメールが検出されたときにエージェントが言うこと | | `end_call_phrases` | `[]` | 通話終了を自動的にトリガーするフレーズ — 例：`["goodbye", "talk later"]` | | `job_description` | — | 通話時にシステムプロンプトの先頭に `# Role` ブロックとして追加。LLM のシステムプロンプト全体を編集せずにエージェントの役割を設定するために使用 | | `speed` | `1.0` | トップレベルの発話速度倍率（0.5〜2.0）。設定時は `tts.speed` を上書き | | `background_sound` | — | エージェントの声の背後に流れるアンビエント音声 — 例：`"office"`、`"cafe"` | | `emotions` | `false` | 感情対応の音声表現を有効化（プロバイダー依存） | *** ## ダイナミック変数 ダイナミック変数を使うと、リードごとに別のエージェントを作成せずに、エージェントの `first_message`、`voicemail_message`、`system_prompt` を通話ごとに個別化できます。これらのフィールドのプレースホルダーは **シングルブレース**（`{variable_name}`）で書き、通話開始時に実際の値を渡します。 ```bash theme={null} # 1. プレースホルダー付きのエージェント curl -X POST https://api.oneinbox.ai/v1/agents \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "Sales Bot", "first_message": "Hi {lead_name}, this is Aria calling about {product_name}.", "dynamic_variables": { "product_name": "Acme Outreach" } }' # 2. 通話ごとの値を渡す curl -X POST https://api.oneinbox.ai/v1/calls \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "agent_id": "", "to_number": "+919876543210", "from_number": "+15739693824", "variables": { "lead_name": "Priya" } }' ``` エージェントは次のように始めます：**「Hi Priya, this is Aria calling about Acme Outreach.」** **2 つのレイヤー — 組み合わせ方：** | レイヤー | 設定場所 | 優先度 | | --------------------------- | -------------------- | -------------------- | | エージェントの `dynamic_variables` | エージェント設定 — すべての通話で同じ | 低い（デフォルトのフォールバック） | | 通話の `variables` | 通話リクエスト — 通話ごと | 高い（エージェントのデフォルトを上書き） | 通話開始時、OneInbox は両レイヤーをマージして最終的な変数マップを作成し（衝突時は通話の値が優先）、エージェントが話し始める前にテンプレート内のすべての `{placeholder}` を置き換えます。LLM と TTS は解決済みの文字列のみを受け取ります — 生のプレースホルダーは渡されません。 **シングルブレース** を使用してください — `{lead_name}`（`{{lead_name}}` ではない）。ダブルブレースは補間されず、リテラルテキストとして表示されます。 *** ## エージェントを更新する いつでもエージェントの任意のフィールドを更新できます。変更は次の通話から有効になります — 進行中のアクティブな通話には影響しません。 ```bash theme={null} curl -X PATCH https://api.oneinbox.ai/v1/agents/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "first_message": "Hi! How can I help you today?", "silence_timeout_seconds": 15 }' ``` *** ## エージェントを管理する ### すべてのエージェントを一覧表示 アカウント内のすべてのエージェントを取得します。他の操作で必要な `agent_id` や `llm_id` を見つけるために使用します。 ```bash theme={null} curl "https://api.oneinbox.ai/v1/agents?limit=20" \ -H "Authorization: Bearer " ``` ### 特定のエージェントを取得 1 つのエージェントの完全な設定を取得します — `llm_id`、言語、音声設定、すべての動作フィールドを含みます。 ```bash theme={null} curl https://api.oneinbox.ai/v1/agents/ \ -H "Authorization: Bearer " ``` 単一エージェントの GET には読み取り専用の `effective_system_prompt` フィールドが含まれます — 通話時にエージェントに渡される正確なシステムプロンプトです：LLM の `system_prompt` に `job_description` が `# Role` ブロックとして先頭に追加されたものです。これが LLM が実際に受け取るもので、ワーカーが実行時と同じ方法で組み立てられます。 ```json theme={null} { "id": "agt_abc123", "llm_id": "llm_xyz789", "job_description": "You are a friendly sales rep at Acme.", "effective_system_prompt": "# Role\nYou are a friendly sales rep at Acme.\n\nYou are a helpful voice assistant.", "..." } ``` `effective_system_prompt` は `GET /v1/agents/{id}` でのみ入力されます。行ごとの LLM ルックアップを避けるため、リストエンドポイントでは `null` です。通話ごとの変数補間とナレッジベースのチャンクは実行時に解決されるため、ここには反映されません。 ### エージェントを削除する エージェントを永続的に削除します。エージェントが電話番号に割り当てられている場合は、まず番号を別のエージェントに再割り当てしてから削除してください。 ```bash theme={null} # 1. まず電話番号を再割り当て（該当する場合） curl -X PATCH https://api.oneinbox.ai/v1/phone-numbers/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "agent_id": "" }' # 2. エージェントを削除 curl -X DELETE https://api.oneinbox.ai/v1/agents/ \ -H "Authorization: Bearer " ``` ### LLM モデルを一覧表示する ```bash theme={null} curl "https://api.oneinbox.ai/v1/models?limit=20" \ -H "Authorization: Bearer " ``` ### LLM モデルを取得する 特定のモデルの完全な設定（システムプロンプト、ツール、ナレッジベース、カスタム URL）を取得します。 ```bash theme={null} curl https://api.oneinbox.ai/v1/models/ \ -H "Authorization: Bearer " ``` ### LLM モデルを削除する モデルを永続的に削除します。このモデルを現在使用しているエージェントは LLM 設定を失います — 先に `{ "llm_id": "" }` で再割り当てしてください。 ```bash theme={null} curl -X DELETE https://api.oneinbox.ai/v1/models/ \ -H "Authorization: Bearer " ``` *** ## 次のステップ エージェントにアクションを与える — SMS、メール、データ取得、転送 登録済みの電話番号で実際のアウトバウンド通話を行う 通話の分類方法と結果の読み方 利用可能な声を閲覧して TTS を設定する