Agent

session
  .agent({
    stt: {
      vendor: 'deepgram',
      language: 'multi',
      deepgramOptions: { model: 'nova-3-general' },
    },
    tts: {
      vendor: 'cartesia',
      voice: '9626c31c-bec5-4cca-baa8-f8ba9e84c8bc',
    },
    llm: {
      vendor: 'openai',
      model: 'gpt-4.1-mini',
      llmOptions: {
        messages: [
          { role: 'system', content: 'You are a helpful voice assistant.' },
        ],
        tools: [
          {
            name: 'get_weather',
            description: 'Get current weather for a city',
            parameters: {
              type: 'object',
              properties: {
                city: { type: 'string' },
              },
              required: ['city'],
            },
          },
        ],
      },
    },
    turnDetection: 'krisp',
    earlyGeneration: true,
    bargeIn: { enable: true, minSpeechDuration: 0.5 },
    noResponseTimeout: 12,
    toolHook: '/tool-call',
    eventHook: '/agent-event',
    actionHook: '/agent-complete',
  })
  .send();

agent Function は、STT、LLM、TTS の3つのコンポーネントをターン検出と統合して組み合わせ、完全な音声AIエージェントを構成します。llm Function(OpenAI Realtime などの speech-to-speech API に接続します)とは異なり、agent Function では各コンポーネントごとに別々のベンダーを自由に組み合わせることができます。

agent Function は、会話ターンの一連のサイクル全体を管理します。

1. ユーザーが話す → STT が文字起こし結果を生成する
2. ターン検出がユーザーの発話終了を判定する
3. 文字起こし結果が LLM に送信される
4. LLM の応答トークンが TTS にストリーミングされる
5. TTS の音声が発信者に再生される
6. ユーザーがバージインした場合、TTS が停止し、新しいターンが始まる

パラメータ

agent Function の終了時に呼び出される Webhook です。ペイロードには、終了理由を示す completion_reason フィールドが含まれます。

アシスタントの発話中にユーザーが割り込めるかどうか、およびその方法を制御します。

アシスタントの発話中にユーザーが割り込むことを許可します。

割り込みとして確定するまでに必要な、検出された発話の秒数です。短い雑音でアシスタントの発話が中断されるのを防ぎます。

true の場合、ユーザーが一度割り込むと、アシスタントは中断された応答の発話を再開しません。

ターン終了が確定する前に、LLM への投機的なプロンプト送信を有効にします。Krisp のターン検出を使用する場合、これを true に設定すると、Krisp がターン終了を確定する前に LLM へ投機的にプロンプトを送信します。ターン終了時に文字起こし結果が一致すれば、バッファされたトークンが即座に解放され、応答レイテンシが短縮されます。Deepgram Flux は、この設定にかかわらず自動的に早期生成を行います。

エージェントのイベントに対して呼び出される Webhook です。受信するイベントタイプは user_transcript、agent_response、user_interruption、turn_end、history_summarized です。後述の eventHook イベント を参照してください。

ユーザーが話す前に、LLM が最初の挨拶を生成するかどうかを指定します。エージェントがユーザーの最初の発話を無言で待つようにしたい場合は false に設定します。

宣言的な有人転送の設定です。指定されている場合、ランタイムは LLM のツールセットに transfer_to_human ツールを注入し、モデルがそれを呼び出すとパッケージ化された transfer の一連の処理を実行します。 有人転送(ハンドオフ) を参照してください。

組み込みの hangup ツールを有効にします。指定されている場合、ランタイムは LLM のツールセットに hangup ツールを注入し、LLM がそれを呼び出すと通話が終了します。後述の 組み込み Hangup ツール を参照してください。

発信する BYE の X-Reason SIP ヘッダーに設定されるデフォルトの理由です。通話時に LLM が独自の理由を指定しなかった場合のフォールバックとして使用されます。

この Function インスタンスの任意の一意識別子です。

LLM の設定です。これが唯一の必須プロパティです。対応ベンダーの一覧は 対応 LLM ベンダー を参照してください。

LLM ベンダー id です。次のいずれかを指定します: anthropic、azure-openai、baseten、bedrock、deepseek、google、groq、huggingface、moonshot、openai、vertex-gemini、vertex-openai、xai、zai。

モデル名です。形式はベンダーごとに異なります(例: gpt-4o-mini、claude-haiku-4-5-20251001、gemini-2.5-flash、llama-3.3-70b-versatile、meta-llama/Llama-3.3-70B-Instruct)。Azure OpenAI の場合は、モデル id ではなく デプロイ名 を指定します。

同一ベンダーに対して複数の LLM 認証情報がアカウントに登録されている場合にのみ必要です。認証情報の作成時にそれぞれ異なるラベルを付け、ここで明示的に参照します。ほとんどのアカウントではベンダーごとに認証情報は1つなので、未設定のままにしてください。

インラインの認証情報です。形式はベンダーによって異なります。指定しない場合、Wipple CPaaS はアカウントに設定された LLM 認証情報から vendor(および、まれな複数認証情報のケースでは label)をもとに認証情報を検索します。

システムプロンプト、ツール、生成パラメータなどの LLM オプションです。

会話の初期メッセージです。通常は指示を含むシステムメッセージを含めます: [{ role: 'system', content: '...' }]。

LLM のシステムプロンプトです。messages にシステムメッセージを含める代わりに使用できます。

LLM が利用できるツール/関数の定義です。OpenAI の function-calling 形式を使用します。後述の ツール呼び出し を参照してください。

LLM の応答に含まれるトークンの最大数です。

LLM にツールを提供する外部 MCP サーバーです。agent Function は起動時に各サーバーへ接続し、利用可能なツールを検出して、LLM から呼び出せるようにします。各エントリには url プロパティが必須で、任意で auth と roots を指定できます。

背景雑音を低減するためのサーバー側ノイズ除去を有効にします。文字列として指定する場合は、デフォルト設定で使用するために "krisp" または "rnnoise" を渡します。オブジェクトとして指定する場合は { mode: "krisp", level: 80, direction: "read" } のようにします。direction には "read"(発信者の音声をフィルタ、デフォルト)または "write"(送出する音声をフィルタ)を指定できます。Krisp の利用可否はサービスプランによって異なります。

アシスタントの発話終了後、ユーザーに応答を促すまでに待機する秒数です。トリガーされると、ユーザーがまだいるかどうかを確認するためのシステムキューが LLM にプロンプトとして送られます。無効にするには 0 を設定します。

音声認識 (STT) の設定です。利用可能なプロパティは recognizer を参照してください。主なプロパティは vendor、language、hints、および deepgramOptions のようなベンダー固有のオプションです。

LLM がツール/関数の呼び出しを要求したときに呼び出される Webhook です。ペイロードには tool_call_id、name、arguments(すでにオブジェクトとしてパース済み)が含まれます。後述の ツール呼び出し を参照してください。

音声合成 (TTS) の設定です。利用可能なプロパティは synthesizer を参照してください。主なプロパティは vendor、voice、language、およびベンダー固有の options です。

ターン検出の方式です。agent Function がユーザーの発話終了を判定するタイミングを制御します。

文字列として指定する場合:

• "stt" — STT ベンダーのネイティブな発話終了シグナルを使用します。ほとんどのベンダーでは無音ベースです。より高度なターン検出を内蔵しているベンダー(deepgramflux、assemblyai、speechmatics)は、この設定にかかわらず常にネイティブの検出を使用します。
• "krisp" — 単なる無音ではなく発話パターンを分析する、Krisp の音響的ターン終了モデルを使用します。

オブジェクトとして指定する場合(Krisp のみ):

• mode — "krisp"(必須)
• threshold — 信頼度のしきい値(0.0〜1.0)。値が小さいほど早くターンが切り替わります。デフォルト: 0.5。
• model — 任意の Krisp モデル名のオーバーライド。

ツール呼び出し

llm.llmOptions.tools でツールを定義し、toolHook で呼び出しを処理します。ツール呼び出しのペイロードには tool_call_id、name、arguments(パース済み。JSON 文字列ではなくオブジェクト)が含まれます。

WebSocket モード では、session.sendToolOutput(tool_call_id, result) で応答します。

session.on('/tool-call', async (evt) => {
  const { tool_call_id, name, arguments: args } = evt;
  if (name === 'get_weather') {
    const weather = await fetchWeather(args.city);
    session.sendToolOutput(tool_call_id, weather);
    return;
  }
  session.sendToolOutput(tool_call_id, `Unknown tool: ${name}`);
});

Webhook モード では、HTTP レスポンスボディにツールの結果を JSON として返します。

または、外部の MCP サーバー に接続して、インラインで定義することなくツールを自動的に提供することもできます。

MCP サーバー

ツールをインラインで定義する代わりに(または加えて)、外部の MCP サーバーに接続できます。agent Function は起動時に SSE または Streamable HTTP トランスポートで各サーバーへ接続し、利用可能なツールを検出して、LLM から呼び出せるようにします。

session
  .agent({
    llm: { vendor: 'openai', model: 'gpt-4.1', llmOptions: {
      messages: [{ role: 'system', content: 'You are a sports assistant.' }],
    }},
    stt: { vendor: 'deepgram', language: 'en-US' },
    tts: { vendor: 'cartesia', voice: 'sonic-english' },
    mcpServers: [
      { url: 'https://livescoremcp.com/sse' },
    ],
    actionHook: '/agent-complete',
  })
  .send();

LLM がツール呼び出しを要求すると、agent Function はまず MCP サーバーを確認します。ツール名が MCP サーバーから検出されたものと一致する場合、呼び出しはそのサーバーへ直接ディスパッチされます。どの MCP サーバーもそのツールを提供していない場合は、toolHook にフォールスルーします。

有人転送(ハンドオフ)

handoff ブロックを追加すると、エージェントが発信者を人間のオペレーターへ転送できるようになります。ランタイムは LLM のツールセットに transfer_to_human ツールを注入するため、このツール用の toolHook を書く必要はありません。 発信者が人間との対話を求め、モデルがこのツールを呼び出すと、Wipple CPaaS はパッケージ化された transfer の一連の処理を、設定された転送先に対して実行します。

session
  .agent({
    stt: { vendor: 'deepgram', language: 'en-US' },
    tts: { vendor: 'cartesia', voice: 'sonic-english' },
    llm: { vendor: 'openai', model: 'gpt-4.1', llmOptions: {
      messages: [{ role: 'system', content: 'You are a helpful support agent.' }],
    }},
    handoff: {
      mode: 'blind',
      blindMethod: 'dial',
      brief: 'none',
      target: [{ type: 'user', name: 'agent-desk@sip.example.com' }],
    },
    actionHook: '/agent-complete',
  })
  .send();

handoff ブロックには、transfer のすべてのオプション(mode、 target、blindMethod、disposition、confirm など)に加えて、次のものを指定できます。

ウォーム転送時に人間のオペレーターへ読み上げられる要約を制御します。'auto' は LLM に要約を書かせます。'none' は読み上げによる要約を送りません(注入されるツールも 引数なしのままになります)。{ template: '...' } は LLM の要約をガイドします。

読み上げ要約に使用する任意の音声/ベンダー(synthesizer オブジェクト)です。 デフォルトはセッションの合成エンジンです。

注入されるツール名をオーバーライドします。

LLM に提示される、注入されるツールの説明をオーバーライドします。

人間側の通話レグがブリッジされると、エージェントの actionHook が転送結果を報告します( transfer の actionHook プロパティ を参照してください)。

組み込み Hangup ツール

hangup を設定すると、LLM が自ら通話を終了できるようになります。ランタイムは LLM のツールセットに hangup ツールを注入します。このツールは llm.llmOptions.tools で定義する必要はなく、toolHook で処理する必要もありません。ランタイムが呼び出しをインターセプトして通話を切断し、agent Function を終了します。

session
  .agent({
    llm: { vendor: 'openai', model: 'gpt-4.1-mini', llmOptions: {
      messages: [{ role: 'system', content: 'You are a helpful assistant. When the caller says goodbye, call the hangup tool.' }],
    }},
    stt: { vendor: 'deepgram', language: 'en-US' },
    tts: { vendor: 'cartesia', voice: '9626c31c-bec5-4cca-baa8-f8ba9e84c8bc' },
    hangup: { reason: 'conversation complete' },
    actionHook: '/agent-complete',
  })
  .send();

注入されるツールは任意の reason 引数を受け付け、LLM は通話を終了すると判断した際にこれを指定できます。発信する BYE の X-Reason SIP ヘッダーに設定される理由は、次の順序で決定されます。

1. LLM が指定した reason 引数(存在する場合)。
2. なければ、アプリケーションが設定した hangup.reason のデフォルト値(設定されている場合)。
3. それもなければ、X-Reason ヘッダーは送信されません。

デフォルトの理由なしでツールを有効にするには、空のオブジェクト(hangup: {})を渡します。

注意

LLM が hangup ツールを呼び出すと、通話は即座に切断されます。actionHook は(completion_reason: "hangup" で)引き続き呼び出されますが、そこから返される後続の Function は、通話がすでに終了処理中であるため破棄されます。

eventHook イベント

eventHook は会話中のイベントをリアルタイムに受信します。WebSocket モードでは、session.on('/your-event-hook', handler) でリッスンします。

turn_end

各会話ターンの終了時に送信されます。可観測性の観点で最も有用なイベントです。

{
  "type": "turn_end",
  "transcript": "What's the weather in Portland?",
  "confidence": 0.998,
  "response": "The current temperature in Portland is 52°F with wind speed 12 km/h.",
  "interrupted": false,
  "latency": {
    "stt_ms": 320,
    "eot_ms": 180,
    "llm_ms": 890,
    "tool_ms": 420,
    "tts_ms": 210,
    "preflight": {
      "result": "hit",
      "tokens": 12
    }
  },
  "tool_calls": [
    { "name": "get_weather", "rtt_ms": 420 }
  ]
}

レイテンシフィールド(すべてミリ秒):

• stt_ms — STT の処理時間(ユーザーの発話終了 → 最終的な文字起こし結果の受信)
• eot_ms — 文字起こし結果の受信後、ターン終了検出までの追加の待機時間
• llm_ms — LLM の純粋な思考時間(ツールの RTT を差し引いたもの)
• tool_ms — ツール呼び出しに費やした合計時間
• tts_ms — TTS エンジンのレイテンシ(テキスト送信 → 最初の音声受信)
• preflight — 早期生成のメトリクス: result(hit、miss、pending のいずれか)と、hit 時にバッファされた tokens

user_transcript

ユーザーの最終的な文字起こし結果が利用可能になったときに送信されます。

{
  "type": "user_transcript",
  "transcript": "What's the weather in Portland?"
}

agent_response

LLM が応答の生成を完了したときに送信されます。

{
  "type": "agent_response",
  "response": "The current temperature in Portland is 52°F."
}

user_interruption

アシスタントの発話中にユーザーがバージインしたときに送信されます。

{
  "type": "user_interruption"
}

history_summarized

会話履歴の要約が完了したときに送信されます(JAMBONES_PIPELINE_SUMMARIZE_TURNS 環境変数が必要です)。

{
  "type": "history_summarized",
  "turn": 8,
  "messages_dropped": 5,
  "messages_kept": 6,
  "summary": "The user is a software developer looking for a MacBook Pro..."
}

会話中の更新

agent Function は、会話の進行中に非同期で更新を行うことをサポートしています。更新は WebSocket(session.updateAgent(data))または REST API 経由で送信できます。

update_instructions

会話の途中で LLM のシステムプロンプトを置き換えます。

session.updateAgent({
  type: 'update_instructions',
  instructions: 'You are now a billing support agent.',
});

inject_context

LLM の会話履歴にメッセージを追加します。インラインのシステムメッセージをサポートしていないベンダーの場合、システムメッセージはシステムプロンプトへ振り分けられます。

session.updateAgent({
  type: 'inject_context',
  messages: [
    { role: 'user', content: 'CRM context: Customer name: Sarah Mitchell. Account tier: Gold.' },
  ],
});

update_tools

LLM が利用できるツールセットを置き換えます。

session.updateAgent({
  type: 'update_tools',
  tools: [
    {
      name: 'transfer_call',
      description: 'Transfer the caller to a specialist',
      parameters: { type: 'object', properties: { department: { type: 'string' } } },
    },
  ],
});

generate_reply

LLM に新しい応答の生成を促します。現在の応答をキャンセルして即座に生成するには interrupt: true を使用します。

session.updateAgent({
  type: 'generate_reply',
  interrupt: true,
  user_input: 'URGENT: Tell the customer about the flash sale.',
});

対応 LLM ベンダー