> ## Documentation Index
> Fetch the complete documentation index at: https://onbridge.jp/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# クイックスタート
> 日本語で応答する音声AIエージェントを立ち上げて、電話で話せるようにするところまで、ステップバイステップのチュートリアルです。
## 概要
このチュートリアルでは、音声AIエージェントを立ち上げて、そこに電話番号を与え通話することを行います。以下に解説する内容の見通しをよくするために、まずは全体像について解説します。
AIエージェントと電話を繋ぐ方法には様々ありますが、ここではLiveKit（WebRTCのプラットフォーム）にSIP接続の設定をして、WebRTCのインフラを活用して実現する方法を案内します。
LiveKitにSIP設定するためには、電話回線で送られてくる情報をLiveKitに送るサービスを利用する必要があります。この様なサービスは一般的に"SIP Trunk"と呼ばれます。"onBridge"は日本国内でのAI利用に最適化したSIP Trunkサービスですので、LiveKitへの接続は少ない手数で可能となります。
以下が全体を示す模式図です。完全に正確なものではありませんが、全体感をつかむ参考にしてください。
LiveKitはSIP接続に対応したWebRTCプラットフォームです。SIPによる着信を受けるとRoomを用意し、音声AIエージェントと電話してきた人をその部屋に追加し互いに話せる様にします。
## 手順
本チュートリアルの手順を紹介します。
1. LiveKit で今回のチュートリアルで使うためのプロジェクトを管理画面で設定します。（"プロジェクト"はLiveKitの管理単位です）
2. LiveKit社が提供するAI Agentフレームワークである"LiveKit Agent"で作った小規模なエージェントをLocalで起動します。
3. LiveKitの"サンドボックス"機能でWebRTCでエージェントと会話をテストします。
4. 正しく動作確認ができたら、次は onBridge に LiveKit と接続する設定を行います。
5. LiveKit側のテレフォニー設定を行います。
## LiveKitのプロジェクト作成
[LiveKit](https://livekit.io/)にアカウントを作成し、左下メニューから"Create new project"で新しいプロジェクトを作ります。
出てきたポップアップ画面で任意のプロジェクト名をつけて保存してください。
## LiveKit Agentを使ったミニエージェントをローカルで起動する
最小構成で動作するLiveKit Agentのサンプルリポジトリを用意しています。こちらをクローンしてください。
TypeScript版 LiveKit Agent 最小構成サンプル：[https://github.com/sparkleai/mini-livekit-agent-js](https://github.com/sparkleai/mini-livekit-agent-js)
### パッケージインストール
```
npm install
```
### 環境変数の設定
音声認識(STT)にDeepgram、推論と音声合成(TTS)にはOpenAIのAPIを使う設定になっています。以下の内容を各サービスから取得し`.env`に設定してください。
* OpenAI : [https://platform.openai.com/](https://platform.openai.com/)
* Deepgram: [https://deepgram.com/](https://deepgram.com/)
LiveKitの環境変数取得方法については、3つの設定を一度にコピーできる機能がありますので、この後に案内します。
```
LIVEKIT_URL=
LIVEKIT_API_KEY=
LIVEKIT_API_SECRET=
DEEPGRAM_API_KEY=
OPENAI_API_KEY=
```
### LiveKitのキーの取得
左メニューからSettings > API keysに進んでください。
デフォルトで API キーの設定が一つできていますので、そちらをクリックし詳細ダイアログを出します。ダイアログ中に "Reveal secret" ボタンがありますので、そちらをクリック。Secret が表示されます。この状態でEnvironment variablesのコピーボタンをクリックするとクリップボードにコピーされます。`.env` へペーストして保存してください。
`.env` の設定は次の様になります
## プログラムのローカルでの起動
以下のコマンドでLiveKitエージェントを起動してください。
```
npm run start
```
LocalでLiveKit Worker が起動し LiveKit Cloud のプロジェクトに登録され、LiveKit Agent がいつでも通話に参加できる様に待機している状態になります。
## LiveKit サンドボックスでテストする
LiveKit Cloudには、プロジェクトごとに独立した環境で サンプルアプリケーションをDeployして試せる機能（Sandbox）がついています。Voice assitantのサンプルは、プロジェクトに登録されている 音声Agentと会話できる WebRTCクライアントのサンプルです。これを利用して今 Localに立ち上がっている LiveKit Agentのサンプルと会話テストをしてみましょう。
LiveKit の Sandbox メニューに進み、"Voice assistant" を選択してください。
"Run in sandbox" ボタンをクリックします。
次の様なダイアログが表示されますが、ここは何もせず "Done" ボタンをクリックして閉じてください。
戻った画面で "Sandbox apps" 項目に "VOICE-ASSISTANT" が追加されていますので、"Launch" ボタンをクリックしてください。
出てきた画面で、"START A CONVERSATION" ボタンをクリックすると会話が始まります。初回には、ブラウザにマイクの使用許可を求めるポップアップが出ますので、許可をしてください。
会話ができることを確認して、終わったら "X"ボタンで終了してください。
## 電話接続の設定を行う
LiveKitのプロジェクトに onBridge経由でダイヤルインできる様にするには、次の手順を行います。
1. onBridgeで電話番号を取得します。
2. LiveKitで"SIP URL"を取得し、onBridgeで使いたい電話番号の設定として、そのSIP URLを設定します。
3. LiveKitで"Inbound Trunk"の設定を行います。具体的には、取得した電話番号をアサインします。
4. LiveKitで"Dispatch Rule"の設定を行います。個別のコールに対してルームアサインの方法や通話するエージェントの種類などを設定します。
### onBridgeで電話番号を取得
onBridgeの開発者向けプラン(Developer Plan)では、クレジットカードを登録するだけで電話番号を即日に取得できます。
### LiveKitのSIP URLの取得とonBridgeへの登録
LiveKitのSIP URLはプロジェクトのSettingメニュー"SIP URI"の項目から確認できます。こちらをコピーしてください。
なお、LiveKitでは`sip:`という様にスキーム付きで表示されていますが、onBridgeではスキーム部分は不要ですの`sip:`以下をコピーしてください。
onBridgeの電話番号管理画面で電話番号の詳細設定にすすみ、"接続設定(SIP)"タブの"SIP FQDN"にURLを設定し「設定を保存」ボタンを押して保存してください。
### LiveKitのInbound Trunk と Dispatch Ruleの設定
最後に、LiveKit側に取得した電話番号をSIP接続する設定と、電話がかかってきたときにどの様な挙動を行うかを決めるDispatch Ruleを登録しましょう。
この設定にはLiveKit CLIを使います。お使いの環境に応じて、以下のリンク先の内容に従って、セットアップしてください。
[https://docs.livekit.io/home/cli/cli-setup/](https://docs.livekit.io/home/cli/cli-setup/)
lkコマンドが使える様になります。上のページで紹介されいた通り、LiveKit Cloudを利用している場合はlk cloud authコマンドによりクレデンシャルの入力を省略することができますので、コマンドをうち、指示に従ってログインをします。
```
lk cloud auth
```
CLIの指示に従ってDeviceの選択などを行った後、Browserが自動起動します。ブラウザ側でアクセスを許可するプロジェクトを選択し、"Allow access"ボタンをクリックしてください。
ブラウザ側で設定完了すると、ターミナルに戻る様に指示が出ます。ターミナルでは今設定したプロジェクトをデフォルトに設定するかどうかを尋ねられます。デフォルトに設定しておくと、後のコマンドを入力するときにプロジェクトの選択を省略できる様になります。
本チュートリアルでは、ここまでのプロジェクトがデフォルトに設定されている前提で進めます。
後でデフォルトを変えたくなった`lk project set-default <プロジェクト名>` で切り替えることができます。
### Inbound Trunkの設定
Inbound Trunkの設定を進めるにあたり、事前に適当な場所に次のような設定用ファイルを作っておきましょう。
"name"と"numbers"という要素を持ったobjectをinbound.jsonとして保存します。"numbers"項目は、このInbound Trunkで受け付ける電話番号のリストです。電話番号の表記方法とし`E.164`形式を取る必要があります。`+` 記号と日本の国番`81`につづけて、電話番号の頭の0を省略した番号を続けて書きます。
下のサンプルは`050-5555-1234` という架空の番号を設定した場合のサンプルです。実際に利用する電話番号に変更して記述してください。
```inbound.json theme={null}
{
"trunk": {
"name": "tutorial",
"numbers": ["+815055551234"]
}
}
```
`inbound.json`を保存した同じ階層で次の様にコマンドしてください。inbound trunkの保存ができる`SIPTrunkID`が表示されます。
```
lk sip inbound create inbound.json
```
```
lk sip inbound list
```
で設定されていることが確認できます。また、LiveKit Cloud側でも `Telephony > Configuration` メニューからGUIで確認できます。
### Dispatch Ruleの設定
最後にDispatch Ruleを設定します。LiveKitのDispatch Ruleとは、コールをどのようにLiveKitのRoomやWorker(つまり担当するエージェント)にルーティングするかを制御するルールセットです。
次の様なJSONファイルを用意します。
```dipatch.json theme={null}
{
"name": "tutorial",
"rule": {
"dispatchRuleIndividual": {
"roomPrefix": "call-"
}
}
}
```
個別Dispatchルールでは、電話がかかってきた時、それぞれ個別に別のRoomを立ち上げるか、一つのRoomに全員を入れるかといった設定や、Roomを作る時の命名規則、またRoomに追加するAgentを何にするかといったルーティングのルールを設定できます。
上記では、コール毎に個別のRoomを作ります。そのときRoom名はデフォルトで「{発信者電話番号}-{ランダムな値}」になりますが、ここにPrefixに"call-"をつけて、「call-{発信者番号}-{ランダムな値}」にする設定です。
Dispatch ルールを登録します。
```
lk sip dispatch create dispatch.json
```
正しく登録ができればDispatch RuleのIDが表示されます。
## テスト通話とトラブルシューティング
これで全ての設定が終わりました。onBridgeで取得した電話番号に電話を掛けて、音声AIエージェントと通話ができることを確認してください。
うまく通話できなかったときは、以下のことを確認し、修正してください。
### ピピピっと音がなるが、電話がかからない場合
電話のルーティングに失敗している可能性があります。以下の部分を順番に確認してください。
1. 発信者番号がonBridgeのSMS認証を受けていること。\
Developerプランはテスト目的での利用に制限されているため、利用できる番号は同じオーガニゼーションに所属するSMS認証済み番号に限られています。\
onBridgeの電話番号管理画面で、着信＆発信が可能な電話番号のリストが確認できますので、そこに登録されている番号からテストしてください。
2. onBridgeに正しくLiveKitのSIP URLが登録されていること。\
onBridgeの管理画面にログインし、取得している電話番号の設定を確認してください。
3. LiveKitのInbound Trunkの電話番号が、onBridgeで取得した番号であっていること。\
LiveKit Cloundにログインし、Telphony > Configuration メニューに移動します。設定されている番号が取得している番号と等しいことを確認してください。
4. Dispatchルールが正しく登録されていること。\
上記と同じ画面でDispatchルールが登録されていることを確認してください。
### コール音はなるが、音声エージェントが通話に出ない
エージェントが立ち上がっていないか、LiveKitのプロジェクトにエージェントが正しく登録されていない可能性があります。以下の部分を順番に確認してください。
1. Localでエージェントが立ち上がっていること。\
エージェントプログラムが正しく起動して待機状態であるかを確認してください。もし待機状態でない場合は待機状態にしてください。
2. エージェント`.env` 設定が正しいこと。\
LiveKit CloudのSettings > API keys メニューに進み、利用しているAPIの詳細画面を開きます`LIVEKIT_URL` / `LIVEKIT_API_KEY` / `LIVEKIT_API_SECRET` それぞれの値が、正しくエージェントの `.env` に保存されていることを確認します。もし異なっていれば修正し、エージェントを立ち上げ直してください。
## 改善・応用について
ここで利用している音声エージェントのサンプルは最小構成です。次の様な改善を通して音声AIエージェントの開発を進めていきましょう。
* STT や TTSのモデルを他の、より高速なものに変更する
* LLMのモデルや、プロンプトを変更して応答を改善する
* Function Calling（Tool Calling）を追加する
* RAG機能を追加して、特定文脈での質問に答えられる様にする
* 終話判定などのターン管理を改善する。