> ## 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. # ツール > 通話中にエージェントへアクションを付与 — メッセージ送信、データ取得、転送、会議予約、自社 API 呼び出し。 ## ツールの仕組み 発信者の発言がツールの「トリガー」（`description` フィールドで定義）に一致すると、エージェントは通話中にそのツールを自動的に発火します。 **重要なポイント:** ツールは **LLM モデル** に紐付けられます。エージェント自体には紐付けません。 ``` エージェント → LLM モデル → ツール ``` 1 つの LLM モデルに複数のツールを持たせることができます。そのモデルを使うすべてのエージェントは、すべてのツールを自動的に継承します。エージェントに新しいツールを追加するには、紐付いている LLM モデルを更新してください — エージェント自体ではありません。 まだエージェントを作成していない場合は、先に [クイックスタート](/jp/guides/quickstart) を参照してください。 *** ## ツール種別 | 種別 | エージェントの動作 | 主な用途 | | ------------------------- | --------------------- | ---------------- | | `api_call` | 自社の HTTP エンドポイントを呼び出す | 照会、CRM 更新、独自ロジック | | `transfer_call` | 電話番号へ転送する | 人間へのルーティング | | `extract_information` | 会話から構造化データを保存する | 名前・メール・予算の取得 | | `end_call` | 通話を終了する | フローをきれいに完了させる | | `send_sms` | テキストメッセージを送信する | フォローアップ、確認連絡 | | `send_email` | メールを送信する | リードの引き渡し、要約 | | `schedule_calendar_event` | カレンダーイベントを予約する | デモ予定、アポイント | *** ## ステップ 1 — ツールを作成する ### `send_sms` トリガーされたときにテキストメッセージを送信します。リードが取得された瞬間にチームへ通知したり、発信者へ確認連絡を送るために使います。 ```bash theme={null} curl -X POST https://api.oneinbox.ai/v1/tools \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "notify_team_sms", "type": "send_sms", "description": "SMS the team when a lead is captured. Trigger when the caller shares their contact details.", "messaging_config": { "to": "caller", "body_template": "New lead: {name} ({phone})" } }' ``` | フィールド | 役割 | | -------------------------------- | -------------------------------------------------------------------------------- | | `description` | エージェントがこのツールを発火するタイミングを決める判断材料 — トリガー条件として書く | | `messaging_config.to` | 文字列 `"caller"`（通話中の相手へ送信）または明示的な E.164 形式の電話番号でチームに通知 | | `messaging_config.body_template` | メッセージ本文。動的な値には `{variable_name}`（シングルブレース）を使用。発信者の電話番号を自動挿入するには `{{caller}}` を使用 | SMS は通話に使用した番号と同じ番号から送信されます — その番号が SMS 機能を有効にしていることを確認してください。OneInbox 経由で番号を購入するか、自分の Twilio/Telnyx 番号を登録する場合は、このツールを使用する前に SMS 対応を確認してください。 `{{caller}}` は通話時に発信者の電話番号へ自動的に解決されるビルトイン変数です — システムが自動的に埋め込みます。メッセージ本文に番号を含めるために発信者へ電話番号を聞く必要はありません。 *** ### `send_email` トリガーされたときにメールを送信します。リードの要約を営業チームに届けたり、発信者へフォローアップメールを送ったり、通話中の重要なタイミングで誰かに通知するために使います。 ```bash theme={null} curl -X POST https://api.oneinbox.ai/v1/tools \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "notify_team_email", "type": "send_email", "description": "Email the sales team when a lead is captured. Trigger when the caller expresses interest.", "credential_id": "", "messaging_config": { "to": "sales@example.com", "subject_template": "New lead: {name}", "body_template": "{summary}" } }' ``` | フィールド | 役割 | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `description` | エージェントがこのツールを発火するタイミングを決める判断材料 — トリガー条件として書く | | `credential_id` | `resend` または `sendgrid` インテグレーションの UUID。メールはそのインテグレーションの `from_email` から送信される — **プロバイダー側でドメイン認証されている必要があり**、未認証だと HTTP 403 で失敗する | | `messaging_config.to` | 送信先メールアドレス。発信者のメールアドレスに送るには `{{email}}` を使用 | | `messaging_config.subject_template` | メールの件名。動的な値には `{variable_name}`（シングルブレース）を使用 | | `messaging_config.body_template` | メール本文。会話から取得した動的な値には `{variable_name}`（シングルブレース）を使用 | 通話ごとにツール発火ではなく、すべての通話終了後に自動でサマリーSMS/メールを送りたい場合は、ツールではなく**エージェント**に `post_call_sms` / `post_call_email` を設定してください — 詳細は [エージェント](/jp/concepts/agents) を参照。ツールはトリガーに基づき通話中に発火しますが、ポストコール設定は通話終了後に一度だけ自動的に発火します。 `{{email}}` は通話開始時に渡される `dynamic_variables` オブジェクトから解決されます — アウトバウンドコールリクエストに `"dynamic_variables": {"email": "caller@example.com"}` を含めることで利用できます。`to`、`subject_template`、`body_template` のどこでも `{{email}}` を使用して発信者のメールアドレスを自動挿入できます。 *** ### `schedule_calendar_event` トリガーされたときにカレンダーイベントを予約します。通話中にエージェントへデモやフォローアップ会議を直接スケジュールさせたいときに使います。 ```bash theme={null} curl -X POST https://api.oneinbox.ai/v1/tools \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "book_demo", "type": "schedule_calendar_event", "description": "Book a product demo when the caller asks to schedule a meeting or demo. Trigger phrases: schedule, book a demo, set up a call.", "credential_id": "", "calendar_config": { "event_type_id": 123456, "duration_minutes": 30, "timezone": "America/New_York" } }' ``` | フィールド | 役割 | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `description` | トリガー条件 — エージェントがいつ発火すべきか明確に伝える（例：「発信者が会議に同意したとき」） | | `credential_id` | `calcom` インテグレーションの UUID。必須 — このツールはこの Cal.com アカウントに対して空き状況を確認し予約する | | `calendar_config.event_type_id` | 予約対象の Cal.com イベントタイプ ID。Cal.com ダッシュボードの URL、または `GET https://api.cal.com/v2/event-types` から取得 | | `calendar_config.duration_minutes` | イベントの長さ（分） | | `calendar_config.timezone` | 予約に使用する IANA タイムゾーン文字列（例：`"Asia/Kolkata"`、`"Asia/Tokyo"`、`"Europe/London"`、`"America/New_York"`）。省略した場合は UTC がデフォルト — 予約が発信者のローカル時間に正しく表示されるよう、発信者のタイムゾーンを設定してください | エージェントは通話中に参加者の**名前とメールアドレス**を取得する必要があります — Cal.com の予約完了にはどちらも必須です。リクエストされた時間枠に空きがない場合（例：Cal.com の稼働時間外）、予約は HTTP 400 で失敗します。 *** ### `api_call` 通話中に自社の HTTP エンドポイントを呼び出します。情報照会（注文状況、アカウント詳細など）、CRM へのデータ送信、発信者の発言に応じた独自ビジネスロジックの実行に使います。 ```bash theme={null} curl -X POST https://api.oneinbox.ai/v1/tools \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "check_inventory", "type": "api_call", "description": "Look up inventory by SKU when the caller asks about stock or availability.", "url": "https://api.example.com/inventory", "method": "POST", "headers": { "Authorization": "Bearer " }, "parameters": [ { "name": "sku", "type": "string", "required": true, "description": "Product SKU the caller mentioned" } ], "run_in_background": true, "speak_during_execution": true }' ``` | フィールド | 役割 | | ------------------------ | ----------------------------------------------------------------- | | `url` | 自社エンドポイントの URL — 外部からアクセス可能である必要がある | | `method` | HTTP メソッド（`GET`、`POST`、`PUT`、`PATCH`） | | `headers` | エンドポイントが要求する認証ヘッダー | | `parameters` | 会話からエージェントが抽出し、API へリクエストボディとして渡すフィールド | | `run_in_background` | `true` = API呼び出しが並行して実行されている間もエージェントは話し続ける。`false` = エージェントは応答を待つ | | `speak_during_execution` | `true` = API呼び出し中にエージェントが「少々お待ちください…」のようなフィラーを発言する | #### ネストしたパラメータ（フル JSON Schema） `parameters` はフラットなフィールドリストのみをサポートします。エンドポイントがネストしたオブジェクト・配列・enum を必要とする場合は、代わりに `parameters_schema` を使用してください — サーバー側で保存前に検証される、生の JSON Schema オブジェクトです。どちらか一方のみを使用してください（両方は不可）： ```bash theme={null} curl -X POST https://api.oneinbox.ai/v1/tools \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "create_ticket", "type": "api_call", "description": "Open a support ticket when the caller reports an issue.", "url": "https://api.example.com/tickets", "method": "POST", "parameters_schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "Ticket subject" }, "priority": { "type": "string", "enum": ["low", "high"] }, "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" } }, "required": ["sku"] } } }, "required": ["subject"] } }' ``` *** ### `transfer_call` 発信者を実際の電話番号へ転送します。発信者が人間との会話を求めたとき、または特定のチームへ繋ぐ必要があるときに使います。OneInbox はコールド（デフォルト）とウォームの 2 つの転送モードをサポートしています。 | モード | 動作 | | --------------- | -------------------------------------------------------------------------- | | **コールド**（デフォルト） | ブラインド SIP REFER — 発信者は即座に引き継がれます。人間は事前のコンテキストなしで電話を受けます。 | | **ウォーム** | エージェントが先に人間へ電話し、発信者のコンテキストを伝え、人間の準備ができてから発信者を接続します。ブリーフィング中、発信者は保留音楽を聞きます。 | #### コールドトランスファー デフォルトです。発信者は即座に転送されます — ブリーフィングも保留音楽もありません。コンテキストの引き継ぎより速度が重要な場合（例：一般サポートキューへのルーティング）に使います。 ```bash theme={null} curl -X POST https://api.oneinbox.ai/v1/tools \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "transfer_to_support", "type": "transfer_call", "description": "Transfer to a human agent when the caller asks to speak to a person or escalate. Trigger phrases: talk to someone, speak to a human, I want a real person.", "transfer_to": "+15105550100" }' ``` `transfer_config` を省略することは `transfer_config.mode: "cold"` と同等です。 #### ウォームトランスファー エージェントが先に人間へ電話し、発信者の名前・問い合わせ内容・関連コンテキストを伝え、人間の準備ができてから発信者をブリッジします。ブリーフィング中、発信者は保留音楽を聞きます。 高価値なリードをセールスマネージャーへ転送するなど、人間がコンテキストを必要とする場合に使います。 ```bash theme={null} curl -X POST https://api.oneinbox.ai/v1/tools \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "warm_transfer_to_supervisor", "type": "transfer_call", "description": "Warm transfer to a supervisor when the caller needs escalation.", "transfer_to": "+15105550100", "transfer_config": { "mode": "warm", "extra_instructions": "スーパーバイザーに挨拶し、発信者の名前と問題を伝え、接続前に準備ができているか確認してください。" } }' ``` | フィールド | 役割 | | ------------------------------------ | ------------------------------------------------------- | | `transfer_to` | 転送先の電話番号（E.164 形式） | | `description` | トリガー条件 — エージェントがいつこのツールを使うか正確に把握できるよう明示する | | `transfer_config.mode` | `"cold"`（デフォルト）でブラインド引き継ぎ、`"warm"` でエージェントが先に人間をブリーフィング | | `transfer_config.extra_instructions` | warm モードのみ — ブリーフィング中にエージェントが人間へ伝えるべき内容を指示 | *** ### `extract_information` 会話が進む中で構造化データを静かに取得します — エージェントは発信者にそれを告知しません。リード資格データの保存、名前・メールの取得、通話からの重要事実の記録に使います。 ```bash theme={null} curl -X POST https://api.oneinbox.ai/v1/tools \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "lead_capture", "type": "extract_information", "description": "Extract lead info from the conversation. Run this once the caller has shared their name and contact details.", "extraction_schema": { "fields": [ { "name": "full_name", "type": "string", "required": true, "description": "Caller full name" }, { "name": "email", "type": "string", "description": "Caller email address" }, { "name": "interested", "type": "boolean", "description": "Whether the caller expressed interest" } ] } }' ``` | フィールド | 役割 | | -------------------------- | ------------------------------------------------------------------------------------------------------- | | `description` | エージェントに抽出の*タイミング*を伝える — フレーズトリガーではなく条件（例：「発信者が確認質問に回答した後」） | | `extraction_schema.fields` | 抽出するフィールドのリスト。各フィールドは `name`、`type`（`string`、`boolean`、`number`）、任意の `required`、抽出を導く `description` を持つ | 取得したデータは通話終了後の通話レコードで確認できます。 *** ### `end_call` 通話をきれいに終了します。フローの最後 — 予約完了後、発信者がさようならと言った後、またはエージェントがタスクを完了したときに使います。このツールがない場合、無音タイムアウトに達するまで通話は継続します。 ```bash theme={null} curl -X POST https://api.oneinbox.ai/v1/tools \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "hangup", "type": "end_call", "description": "End the call cleanly after the agent has completed its task or the caller says goodbye." }' ``` *** ## ステップ 2 — ツールを LLM モデルに紐付ける ツールを作成するだけではアカウント内で利用可能になるだけで、エージェントはまだ使用できません。エージェントに紐付いている LLM モデルに紐付ける必要があります。エージェント作成レスポンスの `llm_id` を使用します — これが通話中の動作を決定する AI の頭脳です。 ```bash theme={null} curl -X PATCH https://api.oneinbox.ai/v1/models/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "tool_ids": ["", ""] }' ``` この `llm_id` にリンクされているすべてのエージェントは即座に変更を反映します — 再起動は不要です。 *** ## ステップ 3 — システムプロンプトを更新する 各ツールの `description` は**トリガー信号**です — LLM がそれを読んでいつツールを自動的に発火するかを決定します。システムプロンプトはエージェントにフローの中で*どのように*ツールを使うかの文脈と順序を与えます。 **ツールは `name` フィールドで参照します**（ツール作成時に設定した `name`）、ツール ID ではありません。LLM はその名前を利用可能なツールと照合し、適切なタイミングで発火します。 ``` You are a helpful sales assistant for Acme Corp. When the caller shares their name and email, use the lead_capture tool immediately. After capturing their info, ask if they'd like to receive a follow-up SMS. If they say yes, use notify_team_sms. If at any point the caller asks to speak to a human, use transfer_to_human. After the task is complete or the caller says goodbye, use end_call. Keep all replies under two sentences. Be warm and direct. ``` `description` はトリガー条件として書いてください（「発信者が X と言ったときに発火」または「発信者が確認質問に答えたら実行」）。システムプロンプトは順序とフローを強化します。両方が LLM に読まれます — `description` が*いつ*を決め、システムプロンプトが*どのように*を決めます。 *** ## 通話後にツール結果を読む 通話終了後、抽出データとツールの活動が通話レコードに表示されます。まず通話を停止し、数秒待ってから取得します： ```bash theme={null} # 1. 通話を停止 curl -X POST https://api.oneinbox.ai/v1/calls//stop \ -H "Authorization: Bearer " # 2. 2〜3秒待ってから取得 curl https://api.oneinbox.ai/v1/calls/ \ -H "Authorization: Bearer " ``` ```json theme={null} { "id": "call_abc123", "status": "completed", "messages": [ { "role": "agent", "content": "Hi! How can I help?" }, { "role": "user", "content": "My name is Sama, my email is sama@acme.com" } ], "outcome": "Interested", "analysis": { "summary": "Caller expressed interest and shared contact details." } } ``` `messages` と `analysis` は通話終了後にのみ利用可能です — 通話がアクティブな間はどちらも空です。 *** ## ツールの管理 ### すべてのツールを一覧表示 アカウント内のすべてのツールを取得します。紐付け・更新が必要なツール ID を見つけるのに便利です。 ```bash theme={null} curl https://api.oneinbox.ai/v1/tools \ -H "Authorization: Bearer " ``` ### ツールを更新 ツールの名前、説明、設定を変更します。例えば、エージェントがツールを発火する感度を上げ下げするためトリガーの説明を更新します。 ```bash theme={null} curl -X PATCH https://api.oneinbox.ai/v1/tools/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "description": "Updated trigger description" }' ``` ### ツールを削除 ツールを永久に削除します。ツールが LLM モデルに紐付いている場合、先に削除対象の ID を除いた更新済みの `tool_ids` 配列でモデルを PATCH して紐付けを解除してください。 ```bash theme={null} curl -X DELETE https://api.oneinbox.ai/v1/tools/ \ -H "Authorization: Bearer " ``` *** ## API リファレンス [ツール作成](/api-reference/tools/create-tool) · [ツール一覧](/api-reference/tools/list-tools) · [ツール更新](/api-reference/tools/update-tool) · [ツール削除](/api-reference/tools/delete-tool)