ドキュメントに
話しかける
スクリーンショット. ローカルで動かしたテンプレート。
- モデル
- ink-2, sonic-3.6
- 言語
- 英語、スペイン語、フランス語、ヒンディー語、日本語
- ライセンス
- Apache-2.0
- 技術スタック
- HonoNode.jsWeb ComponentsesbuildBM25 or OpenAI embeddings
- Cartesia の製品
- Managed AgentsInk 2Sonic 3.6
できること
ウィジェットはどんなサイトでも動き、ほかのライブラリーを必要としません。サーバーは小さなNodeアプリで、検索インデックスをローカルのファイルに保存します。検索は既定でキーワードを照合します。OpenAIのキーがあれば意味で照合するので、ドキュメントと違う言い回しの質問にも強くなります。再インデックスでは、変更されたページだけを処理します。
自分で動かす
デモを動かす
Node 22.22以降で下のコマンドを実行し、
http://localhost:4512を開いてAsk the docsを押し、続けてStart talkingを押します。デモサイトはdocs.cartesia.aiの2ページをコピーしたものです。環境変数 - CARTESIA_API_KEY
play.cartesia.ai/keys- OPENAI_API_KEY
- 任意。検索を
text-embedding-3-smallの埋め込みに切り替える - CARTESIA_AGENT_ID
npm run setup:agentが書き込む- CARTESIA_TOOL_IDS
- 任意。削除すべきツールがわかるように
npm run setup:agentが書き込む。どこからも読み込まれない - ALLOWED_ORIGINS
- ドキュメントのオリジン。カンマ区切り
- PUBLIC_URL, TRUST_PROXY
- プロキシの後ろで動かす場合。
TRUST_PROXY=1にすると、プロキシが付け加えたアドレスでレート制限する
ドキュメントをインデックスする
.mdや.mdxファイルのフォルダーなら
npm run ingest--./my-docs--base-url/docs/を、公開中のサイトならサイトマップのURLを付けてnpm run ingest -- --sitemapを実行します。scriptタグを追加する
Node 22.22以降が動く任意のホストにサーバーをデプロイし、その
widget.jsを指すscriptタグを1つ追加して、ALLOWED_ORIGINSにドキュメントのオリジンを設定します。
コーディングエージェントで作る
どこから始めて、最初に何を読むべきかをコーディングエージェントに伝えるプロンプトです。
Add a voice assistant to my documentation site with a Cartesia Managed Agent. Start from https:/ and follow its AGENTS.md for the commands, files and rules. npm run setup:agent creates the agent and two client tools, search_docs and show_source. The widget gets a 60 second access token with only the agent grant from the Hono server and opens the Managed Agents WebSocket. search_docs results come from POST /api/search and must stay under 4,096 bytes. Index my docs with npm run ingest, either from a folder or with --sitemap. If I don't have a Cartesia API key yet, follow https:/ to get one.
仕組み
この設計にした理由
検索は訪問者のブラウザーで動く
Cartesiaが呼び出せるのは、公開されたHTTPSアドレスにあるツールだけです。クライアントツールは訪問者のブラウザーで動き、ブラウザーが質問をサーバーに渡すので、デモはトンネルなしでlocalhostで動きます。
結果は4,096バイト未満に収める
Cartesiaは4,096バイトを超えるクライアントツールの結果を拒否します。server/search.tsはセクションを順位付けし、今のページを少し優遇し、上位4件を3,800バイト未満の結果にまとめます。
本当の守りはレート制限
サーバーはOriginヘッダーを確認してほかのサイトを拒否しますが、スクリプトはどんなヘッダーでも送れます。アカウントを守っているのは、IPアドレスごとに1分4個、1時間30個というトークンの上限です。
カスタマイズする
プロンプトとツール
scripts/agent-config.tsを編集し、npm run setup:agent -- --forceを実行します。新しいエージェントと2つの新しいツールが作られ、CARTESIA_TOOL_IDSが上書きされるので、先に古いIDを控えておき、play.cartesia.aiで古いエージェントとツールを削除してください。ツール名はwidget/src/tools.tsにもあるので、両方を変更してください。
言語
セットアップの前にAGENT_LANGUAGEをes、fr、hi、jaのいずれかに設定します。プロンプトはもともと訪問者の言語で答えるようになっています。
ベクトルストア
インデックスを読み書きするのはserver/store.tsだけです。数千セクションでは足りなくなったら、pgvectorやSQLiteに置き換えてください。
よくある質問
ほかのサイトに、ウィジェットやAPIキーを使われませんか？
使われません。通話を始められるのは、ALLOWED_ORIGINSに書いたサイトとサーバー自身のアドレスだけです。APIキーはサーバーに残り、ブラウザーが受け取るのは60秒で切れる、エージェントとの通話専用のトークンです。
Cartesiaの組み込みナレッジベースではできないのですか？
ナレッジベースでもドキュメントをもとに答えられます。このテンプレートは自分のサーバーで検索するので、各結果にページのリンクとセクションが付き、ウィジェットはそれを使ってスクロールします。
Docusaurus、Mintlify、Nextraでも動きますか？
はい。scriptタグを追加できる場所ならどこでも動きます。セクションのリンクが見出しと一致するよう、サイトのサイトマップからインデックスしてください。ウィジェットはサイトのダークモード、または訪問者のOSの設定に従います。
別のページへのリンクをクリックすると通話が切れるのはなぜですか？
通話はページの中にあり、複数ページのサイトは移動のたびに再読み込みされます。通話中は、ほかのページにある出典は新しいタブで開きます。
訪問者の通話は録音されますか？
はい。Cartesiaはエージェントのすべての通話の音声と書き起こしを録音します。訪問者に伝え、不要な通話はCartesiaのAPIで削除してください。
このテンプレートの詳しい手順ガイドはありますか？
はい。レシピでコードを順に解説しています。セットアップ、環境変数、デプロイはREADMEに、Cartesia側の仕様はクライアントツールのドキュメントにまとめています。
今すぐ始める
専門家に相談する。
音声体験の開発にCartesiaをどう活用できるか、私たちのチームにご相談ください。
開発を始める。
APIでモデルにアクセスし、数分で音声エージェントを本番環境に導入できます。