> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# カスタムLLMインテグレーション

## 概要

ElevenAgentsの[ネイティブTwilio連携](/docs/ja/eleven-agents/phone-numbers/twilio-integration/native-integration)は、ElevenLabsがLLMをホストするケースに対応しています。独自モデル、RAGパイプライン、関数呼び出しのルーティング、その他のサーバーサイド推論など、LLMの頭脳を自前のサーバーで完全に制御する必要があり、かつエージェントをTwilioの電話番号で運用したい場合は、このガイドを使用してください。

カスタムLLM側は[Speech Engine SDK](/docs/ja/eleven-api/guides/cookbooks/speech-engine)で実現します。これはElevenLabsとサーバーの間にWebSocketを開き、通話の進行に合わせてLLMが応答をストリーミングで返せるようにします。Twilio側では、[Media Streams](https://www.twilio.com/docs/voice/media-streams)を使用して通話オーディオをエージェントへ中継します。

## アーキテクチャ

Speech Engine SDKは、エージェントの会話システム内で2つのWebSocketエンドポイントを公開します。

* **brain WebSocket**はサーバー上で動作します。ElevenLabsはこれに接続し、文字起こしを受け渡してLLM生成テキストを受信します。
* **conversation WebSocket**はElevenLabs上で動作します。クライアントはこれに接続してオーディオを送信し、合成オーディオを受信します。Twilioブリッジは署名付きURL経由で接続し、μ-lawオーディオを双方向に中継します。

Twilio Media StreamsとSpeech Engineはいずれも`ulaw_8000`を使用するため、ブリッジはトランスコードなしでbase64エンコードされたオーディオを中継します。

```mermaid
sequenceDiagram
    participant Caller
    participant Twilio
    participant Bridge as Bridge Server
    participant EL as ElevenLabs (conversation WS)
    participant Brain as Brain Server

    Caller->>Twilio: Dial number
    Twilio->>Bridge: POST /incoming-call
    Bridge-->>Twilio: TwiML <Connect><Stream>
    Twilio->>Bridge: WebSocket /media-stream
    Bridge->>EL: Open conversation WebSocket (signed URL)

    loop Conversation
        Caller->>Twilio: Speak
        Twilio->>Bridge: media event (μ-law base64)
        Bridge->>EL: user_audio_chunk
        EL->>Brain: user_transcript
        Brain-->>EL: agent_response (streamed)
        EL->>Bridge: audio event (μ-law base64)
        Bridge->>Twilio: media event
        Twilio->>Caller: Play audio
    end
```

必要に応じて、ブリッジとbrainサーバーを同じプロセスで実行できます。以下の例では両者を統合しています。

## このパターンを使う場合

このガイドと[ネイティブTwilio連携](/docs/ja/eleven-agents/phone-numbers/twilio-integration/native-integration)は、どちらもエージェントをTwilioの電話番号に割り当てます。違いはLLMを誰が管理するかです。

* **ネイティブ連携**：ElevenLabsがLLMをホストし、エージェントを通じて設定します。よりシンプルです。
* **Speech Engine SDK経由のカスタムLLM**（このガイド）：LLMを自前のサーバーでホストします。モデル、RAG、関数呼び出し、ビジネスロジックを完全に制御できます。構成要素は増えます。

LLMロジックが標準のエージェント設定に収まる場合は、ネイティブ連携をおすすめします。brainで自社インフラ上のコードを実行する必要がある場合は、このガイドを使用してください。

このパターンでは、サーバーとElevenLabs APIの間の通信にWebSocket接続を使うSpeech Engine SDKを使用します。Speech Engine SDKの代わりにOpenAI互換HTTPエンドポイントを使用する[カスタムLLM](/docs/ja/eleven-agents/customization/llm/custom-llm)ガイドも利用できます。

主な違いは、WebSocketかHTTPリクエストかです。WebSocketではターンごとに新しいHTTP接続を確立するのではなく、単一の接続を維持するため、レイテンシーが改善する場合があります。

## 前提条件

* [Twilio](https://www.twilio.com/)アカウントと、音声通話対応の電話番号。
* Speech Engineリソース。[Speech Engineクイックスタート](/docs/ja/eleven-api/guides/cookbooks/speech-engine)に従って作成し、brainサーバーのパターンを確認してください。
* 公開HTTPSトンネル（例：[ngrok](https://ngrok.com)）。Twilioは公開インターネット経由でブリッジに接続します。
* Python 3.9以降またはNode.js 18以降。

## μ-lawオーディオ用にエージェントを設定する

Twilio Media Streamsは8 kHzのμ-lawオーディオを使用します。ブリッジでトランスコードする必要がないよう、Speech Engineが同じ形式を受信・出力するように設定してください。

**`configure_engine.py`**

```python title="configure_engine.py"
import asyncio
import os
from elevenlabs import AsyncElevenLabs

elevenlabs = AsyncElevenLabs(api_key=os.environ["ELEVENLABS_API_KEY"])


async def update_engine():
    await elevenlabs.speech_engine.update(
        speech_engine_id="seng_8k3m9xr4hjnfg983brhmhkd98n6",
        asr={"user_input_audio_format": "ulaw_8000"},
        tts={
            "model_id": "eleven_flash_v2",
            "agent_output_audio_format": "ulaw_8000",
        },
        speech_engine={
            "request_headers": {"x-api-key": os.environ["SHARED_SECRET"]},
        },
    )


asyncio.run(update_engine())
```

**`configure-engine.mts`**

```typescript title="configure-engine.mts"
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import "dotenv/config";

const elevenlabs = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
});

await elevenlabs.speechEngine.update("seng_8k3m9xr4hjnfg983brhmhkd98n6", {
  asr: { userInputAudioFormat: "ulaw_8000" },
  tts: {
    modelId: "eleven_flash_v2",
    agentOutputAudioFormat: "ulaw_8000",
  },
  speechEngine: {
    requestHeaders: { "x-api-key": process.env.SHARED_SECRET! },
  },
});
```

`eleven_flash_v2`はテキスト読み上げのレイテンシーを低く保つため、電話通話で重要です。`request_headers`ブロックは、すべてのbrain WebSocket接続に`x-api-key: <shared-secret>`を含めるようElevenLabsに指示します。brainサーバーはこのヘッダーを確認し、自分のSpeech Engineだけが接続できるようにします。

## ブリッジサーバーを構築する

ブリッジは3つのルートを提供します。

* `POST /incoming-call` — Twilio webhook。Twilioに`/media-stream`へのMedia Streamを開くよう指示するTwiMLを返します。
* `GET /media-stream` — Twilio Media Streams WebSocket。Speech Engine conversation WebSocketとの間でオーディオを中継します。
* `GET /ws` — Brain WebSocket。会話開始時にElevenLabsがここへ接続します。標準の`engine.serve()` / `engine.attach()`サーバーを実行します。

#### 依存関係をインストールする

**`Python`**

```bash title="Python"
pip install "elevenlabs" "aiohttp" "twilio" "python-dotenv"
```

**`Node`**

```bash title="Node"
npm install @elevenlabs/elevenlabs-js express ws twilio dotenv openai
```

#### Speech Engine用の署名付きURLを生成する

ブリッジは新しい通話が着信するたびに署名付きURLをリクエストします。このURLにはSpeech Engine IDと一回限りの署名が埋め込まれるため、ブリッジで生のAPIキーを使用する必要はありません。

**`bridge.py`**

```python title="bridge.py"
from elevenlabs import AsyncElevenLabs

elevenlabs = AsyncElevenLabs(api_key=os.environ["ELEVENLABS_API_KEY"])

async def signed_url() -> str:
    response = await elevenlabs.conversational_ai.conversations.get_signed_url(
        agent_id=os.environ["SPEECH_ENGINE_ID"],
    )
    return response.signed_url
```

**`bridge.mts`**

```typescript title="bridge.mts"
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
});

async function signedUrl(): Promise<string> {
  const response = await elevenlabs.conversationalAi.conversations.getSignedUrl({
    agentId: process.env.SPEECH_ENGINE_ID!,
  });
  return response.signedUrl;
}
```

#### TwiMLレスポンスを返す

通話が着信すると、Twilioは`/incoming-call`へPOSTします。レスポンスは、ブリッジ自身の`/media-stream` WebSocketへのMedia Streamを開くTwiMLです。

**`bridge.py`**

```python title="bridge.py"
from aiohttp import web
from twilio.request_validator import RequestValidator

validator = RequestValidator(os.environ["TWILIO_AUTH_TOKEN"])


async def incoming_call(request: web.Request) -> web.Response:
    form = await request.post()
    signature = request.headers.get("X-Twilio-Signature", "")
    url = str(request.url)
    if not validator.validate(url, dict(form), signature):
        return web.Response(status=403, text="forbidden")

    host = request.headers.get("X-Forwarded-Host") or request.host
    twiml = (
        '<?xml version="1.0" encoding="UTF-8"?>'
        "<Response><Connect>"
        f'<Stream url="wss://{host}/media-stream"/>'
        "</Connect></Response>"
    )
    return web.Response(text=twiml, content_type="text/xml")
```

**`bridge.mts`**

```typescript title="bridge.mts"
import express from "express";
import twilio from "twilio";

const app = express();
app.use(express.urlencoded({ extended: false }));

app.post(
  "/incoming-call",
  twilio.webhook({ validate: true }),
  (req, res) => {
    const host = req.headers["x-forwarded-host"] ?? req.get("host");
    const twiml = `<?xml version="1.0" encoding="UTF-8"?>
      <Response>
        <Connect>
          <Stream url="wss://${host}/media-stream"/>
        </Connect>
      </Response>`;
    res.type("text/xml").send(twiml);
  },
);
```

`RequestValidator`（Python）と`twilio.webhook({ validate: true })`（Node）は、`X-Twilio-Signature`ヘッダーを`TWILIO_AUTH_TOKEN`と照合します。検証しない場合、公開インターネット上の誰でも`/incoming-call`にPOSTでき、アカウントに通話料金が請求される可能性があります。

#### Media Streamをブリッジする

Media Streamは、`connected`、`start`、`media`（オーディオペイロード）、`stop`という一連のJSONイベントを送信するWebSocketです。ブリッジは`start`時にSpeech Engine conversation WebSocketを開き、ストリームが閉じるまでオーディオを双方向に中継します。

**`bridge.py`**

```python title="bridge.py" maxLines=0
import asyncio
import json

import aiohttp
from aiohttp import web


async def media_stream(request: web.Request) -> web.WebSocketResponse:
    twilio_ws = web.WebSocketResponse()
    await twilio_ws.prepare(request)

    stream_sid: str | None = None
    el_session: aiohttp.ClientSession | None = None
    el_ws: aiohttp.ClientWebSocketResponse | None = None
    pump_task: asyncio.Task | None = None

    async def pump_el_to_twilio(el: aiohttp.ClientWebSocketResponse):
        async for msg in el:
            if msg.type != aiohttp.WSMsgType.TEXT:
                continue
            event = json.loads(msg.data)
            etype = event.get("type")
            if etype == "audio":
                await twilio_ws.send_str(json.dumps({
                    "event": "media",
                    "streamSid": stream_sid,
                    "media": {"payload": event["audio_event"]["audio_base_64"]},
                }))
            elif etype == "interruption":
                await twilio_ws.send_str(json.dumps({
                    "event": "clear",
                    "streamSid": stream_sid,
                }))
            elif etype == "ping":
                event_id = event.get("ping_event", {}).get("event_id")
                await el.send_str(json.dumps({
                    "type": "pong", "event_id": event_id,
                }))

    try:
        async for msg in twilio_ws:
            if msg.type != aiohttp.WSMsgType.TEXT:
                continue
            event = json.loads(msg.data)

            if event["event"] == "start":
                stream_sid = event["start"]["streamSid"]
                el_session = aiohttp.ClientSession()
                el_ws = await el_session.ws_connect(await signed_url())
                await el_ws.send_str(json.dumps({
                    "type": "conversation_initiation_client_data",
                }))
                pump_task = asyncio.create_task(pump_el_to_twilio(el_ws))

            elif event["event"] == "media" and el_ws is not None:
                await el_ws.send_str(json.dumps({
                    "user_audio_chunk": event["media"]["payload"],
                }))

            elif event["event"] == "stop":
                break
    finally:
        if pump_task:
            pump_task.cancel()
        if el_ws and not el_ws.closed:
            await el_ws.close()
        if el_session and not el_session.closed:
            await el_session.close()

    return twilio_ws
```

**`bridge.mts`**

```typescript title="bridge.mts" maxLines=0
import { WebSocket, WebSocketServer } from "ws";
import { createServer } from "node:http";

const httpServer = createServer(app);
const wss = new WebSocketServer({ noServer: true });

httpServer.on("upgrade", (req, socket, head) => {
  if (req.url === "/media-stream") {
    wss.handleUpgrade(req, socket, head, (ws) => handleMediaStream(ws));
  } else {
    socket.destroy();
  }
});

async function handleMediaStream(twilioWs: WebSocket) {
  let streamSid: string | null = null;
  let elReady: Promise<WebSocket | null> | null = null;

  twilioWs.on("message", async (raw) => {
    const event = JSON.parse(raw.toString());

    if (event.event === "start") {
      streamSid = event.start.streamSid;
      // Convert rejection into a clean null + close so a failed signed-URL
      // fetch doesn't become an unhandled rejection on the next media event.
      elReady = openElevenLabsWebSocket(twilioWs, () => streamSid).catch((err) => {
        console.error("Failed to open Speech Engine conversation:", err);
        twilioWs.close();
        return null;
      });
    } else if (event.event === "media" && elReady) {
      const elWs = await elReady;
      if (!elWs) return;
      elWs.send(JSON.stringify({
        user_audio_chunk: event.media.payload,
      }));
    } else if (event.event === "stop") {
      twilioWs.close();
    }
  });

  twilioWs.on("close", async () => {
    (await elReady)?.close();
  });
}

async function openElevenLabsWebSocket(
  twilioWs: WebSocket,
  getStreamSid: () => string | null,
): Promise<WebSocket> {
  const elWs = new WebSocket(await signedUrl());
  await new Promise<void>((resolve, reject) => {
    elWs.once("open", () => resolve());
    elWs.once("error", reject);
  });
  elWs.send(JSON.stringify({
    type: "conversation_initiation_client_data",
  }));

  elWs.on("message", (raw) => {
    const event = JSON.parse(raw.toString());
    const streamSid = getStreamSid();
    if (event.type === "audio") {
      twilioWs.send(JSON.stringify({
        event: "media",
        streamSid,
        media: { payload: event.audio_event.audio_base_64 },
      }));
    } else if (event.type === "interruption") {
      twilioWs.send(JSON.stringify({ event: "clear", streamSid }));
    } else if (event.type === "ping") {
      elWs.send(JSON.stringify({
        type: "pong", event_id: event.ping_event?.event_id,
      }));
    }
  });

  return elWs;
}
```

Speech Engineの`interruption`イベントはTwilioストリームで`clear`イベントをトリガーし、バッファリングされたオーディオを破棄するため、割り込み発話がスムーズに機能します。`ping`イベントには`pong`で応答し、conversation WebSocketを維持します。

#### brainサーバーも同時に実行する

brainサーバーは、[クイックスタート](/docs/ja/eleven-api/guides/cookbooks/speech-engine)で示されている標準のSpeech Engineサーバーです。追加するのはWebSocketアップグレード時の共有シークレットチェックだけです。`x-api-key`がSpeech Engineに設定した値と一致する場合にのみ、接続を受け入れてください。

**`bridge.py`**

```python title="bridge.py" maxLines=0
import os

from elevenlabs import AsyncElevenLabs

elevenlabs = AsyncElevenLabs(api_key=os.environ["ELEVENLABS_API_KEY"])
SHARED_SECRET = os.environ["SHARED_SECRET"]


async def brain_ws(request: web.Request) -> web.WebSocketResponse:
    if request.headers.get("x-api-key") != SHARED_SECRET:
        return web.Response(status=401, text="unauthorized")

    ws = web.WebSocketResponse()
    await ws.prepare(request)

    engine = await elevenlabs.speech_engine.get(os.environ["SPEECH_ENGINE_ID"])
    session = engine.create_session(ws)

    async def on_transcript(transcript):
        # Replace this with your own LLM call; see the quickstart.
        await session.send_response("Hello, you've reached the demo.")

    session.on("user_transcript", on_transcript)
    await session.run()
    return ws


def make_app() -> web.Application:
    app = web.Application()
    app.router.add_post("/incoming-call", incoming_call)
    app.router.add_get("/media-stream", media_stream)
    app.router.add_get("/ws", brain_ws)
    return app


if __name__ == "__main__":
    web.run_app(make_app(), port=3001)
```

**`bridge.mts`**

```typescript title="bridge.mts" maxLines=0
httpServer.on("upgrade", async (req, socket, head) => {
  if (req.url === "/ws") {
    if (req.headers["x-api-key"] !== process.env.SHARED_SECRET) {
      socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
      socket.destroy();
      return;
    }
    // Hand off to engine.attach() — see the Speech Engine quickstart.
  } else if (req.url === "/media-stream") {
    wss.handleUpgrade(req, socket, head, (ws) => handleMediaStream(ws));
  } else {
    socket.destroy();
  }
});

httpServer.listen(3001);
```

LLM呼び出しとストリーミング応答を含む完全な`on_transcript`実装については、[Speech Engineクイックスタート](/docs/ja/eleven-api/guides/cookbooks/speech-engine#server-setup)を参照してください。

## Twilioをブリッジに接続する

#### ブリッジと公開トンネルを開始する

```bash
ngrok http 3001
python bridge.py
```

ngrokが表示する`https://` URLを控えてください。TwilioはそこにPOSTします。

#### Speech Engineのws_urlを更新する

ElevenLabsが接続先を認識できるよう、`speech_engine.ws_url`をbrainエンドポイントの公開WebSocket URLに設定してください。

```python
await elevenlabs.speech_engine.update(
    speech_engine_id="seng_8k3m9xr4hjnfg983brhmhkd98n6",
    speech_engine={"ws_url": "wss://abc123.ngrok.io/ws"},
)
```

```typescript
await elevenlabs.speechEngine.update("seng_8k3m9xr4hjnfg983brhmhkd98n6", {
  speechEngine: { wsUrl: "wss://abc123.ngrok.io/ws" },
});
```

#### Twilio番号を設定する

Twilioコンソールで、電話番号の**Voice Configuration**を開きます。

* **A call comes in**：Webhook
* **URL**：`https://abc123.ngrok.io/incoming-call`
* **HTTP method**：POST

番号がElastic SIP Trunkに接続されている場合は、先に切断してください。Twilio番号はトランクまたはwebhookのどちらか一方にのみルーティングでき、両方には設定できません。

#### 番号に電話をかける

任意の電話から番号に発信してください。エージェントが応答します。通話中に話しかけると、エージェントの応答が聞こえるはずです。デバッグログを有効にすると、ブリッジは各ターンの通話SID、会話ID、オーディオ形式を記録します。

## 本番環境での考慮事項

* **Webhookの検証**：`/incoming-call`では必ず`X-Twilio-Signature`を検証してください。上記の例ではTwilioのヘルパーライブラリを使用しています。この手順は省略しないでください。
* **共有シークレット**：brain WebSocketで共有シークレットを必ず適用してください。適用しないと、ngrok URLを推測した第三者が接続し、ElevenLabsになりすます可能性があります。
* **安定したホスト**：ngrok無料プランのURLは再起動のたびに変わります。再起動ごとにSpeech Engineの`ws_url`とTwilio Webhookを更新しなくて済むよう、予約済みのngrokドメインまたは実際のホスト名を使用してください。
* **レイテンシー**：各通話では、LLMの最初のトークンが生成されるまでの時間に加えて、ネットワークホップが2回発生します。低レイテンシーのモデルを使用し、レスポンスをストリーミングして体感レイテンシーを抑えてください。
* **1プロセスまたは2プロセス**：この例では、1つのngrokトンネルですべてをカバーできるよう、bridgeとbrainを同じポートに配置しています。本番環境では、それぞれにパブリックURLがあれば、2つのサービスに分割できます。
* **プロンプトインジェクション**：電話で話された入力は、信頼できないユーザー入力です。ツール呼び出しやデータベースへの書き込みに影響する前に、文字起こしを検証してください。

## 次のステップ

#### [Twilioネイティブ統合](/docs/ja/eleven-agents/phone-numbers/twilio-integration/native-integration)

カスタムLLMの代わりにホスト型LLMを使用します。

#### [Speech Engineクイックスタート](/docs/ja/eleven-api/guides/cookbooks/speech-engine)

ストリーミングLLMを使用して、brainサーバーをエンドツーエンドで構築します。

#### [カスタムLLM（OpenAI互換）](/docs/ja/eleven-agents/customization/llm/custom-llm)

OpenAI互換のHTTPエンドポイントを使用する、別のカスタムLLMの仕組みです。

#### [Python SDKリファレンス](/docs/ja/eleven-api/resources/libraries/speech-engine/python-sdk-reference)

Speech Engine Python SDKのクラス、メソッド、イベント。

#### [JavaScript SDKリファレンス](/docs/ja/eleven-api/resources/libraries/speech-engine/javascript-sdk-reference)

Speech Engine JavaScript SDKのクラス、メソッド、イベント。