Webサイトに話すAIキャラクターを追加する方法
どのWebサイトにも話すAIキャラクターを追加する。Neocortex Web SDK を入れ、APIキーをサーバーに置き、音声チャットの要素を配置し、アクションを処理する。
Sercan AltundasFounder of Neocortex
· 7分で読めます

Webサイトのキャラクターは、案内役、司会、ショップの店員です。訪問者は、ありきたりのチャットの吹き出しではなく、性格と声を持つキャラクターに、自分の言葉で話しかけられます。この記事では、Neocortex Web SDK を使って、どのサイトにも1体追加する方法を説明します。サーバーでは数行、ページには要素を1つ、そしてキャラクターに行動させるための任意のアクションを用意します。
作るもの
ページ上のキャラクターは、次のことができます。
- 入力された質問や話しかけられた質問に、自分の声で答える
- アップロードしたナレッジベースから、あなたのコンテンツを知っている
- 製品を開く、ツアーを始めるなど、ページ上でアクションを実行する
- あなたのAPIキーをブラウザーに決して見せない
必要なもの
- Neocortex のアカウント、APIキー、ダッシュボードで作ったキャラクター
- Node 20 以降、または Cloudflare Workers、Bun、Deno で動くサーバー
- HTTPS で配信されているページ。ブラウザーは、安全なページでしかマイクを許可しないためです
ステップ1: キャラクターをデザインする
Neocortex のエディターで、キャラクターに性格、声、そして製品ページ、FAQ、ツアーのメモからなるナレッジベースを与えます。正しく聞こえるまでブラウザーでテストしてください。エディター内のテストは、どのプランにも含まれます。ダッシュボードからキャラクターのIDをコピーします。
ステップ2: SDK をインストールする
サイトのプロジェクトで npm install @neocortex-link/web を実行します。
ステップ3: サーバーにプロキシを追加する
Neocortex の APIキーは秘密情報です。ページの JavaScript からキーを読み取った人は、あなたのアカウントの利用量を増やせてしまいます。そこで SDK には、キーを保持する小さなサーバー用のハンドラーが含まれています。また、話しかけてくる相手を確認し、あなたが指定したキャラクターだけを許可します。
Next.js のアプリでは、app/api/neocortex/[...path]/route.ts を作成します。
import { createNeocortexHandler } from "@neocortex-link/web/server";
import { auth } from "@/auth";
const handler = createNeocortexHandler({
apiKey: process.env.NEOCORTEX_API_KEY!,
characters: ["your-character-id"],
authorize: async () => {
const session = await auth();
return session?.user ? { id: session.user.id } : null;
},
});
export { handler as GET, handler as POST, handler as OPTIONS };authorize は訪問者を { id } として返すか、拒否する場合は null を返します。その id がキャラクターの playerId になるので、訪問者ごとに個別の会話が持てます。Express の場合は、同じハンドラーを toNodeHandler で包み、/api/neocortex にマウントします。ログインのないサイトでは、署名付きの Cookie で訪問者ごとに安定した id を発行できます。
ステップ4: キャラクターをページに置く
import "@neocortex-link/web/ui/auto" で UI を一度読み込みます(サイトにバンドラーがなければ、CDN の script タグから読み込めます)。そのあと、キャラクターを表示したい場所に要素を置きます。
<neocortex-chat endpoint="/api/neocortex" character-id="your-character-id" voice></neocortex-chat>チャットには、テキストボックスとマイク入力が付きます。voice 属性を付けると、音声での返答が加わります。各行は音声としてストリーミングされ、次の行は現在の行が再生されている間に取得されます。訪問者が話すときにボタンを押し続けてほしいなら push-to-talk を、テキストだけにしたいなら mic="false" を追加します。
要素は標準の Web Components なので、React、Vue、Svelte、Angular、素の HTML で動きます。CSS のカスタムプロパティで、ライトモードとダークモードの両方の見た目を変えられます。複数のキャラクターによるグループチャット(Pro と Team のプラン)と、クイズの司会(Team プラン)の要素もあります。
ステップ5: キャラクターに行動させる
エディターで OPEN_PRODUCT や START_TOUR などのアクションを定義し、ページ側で処理します。
const chat = document.querySelector("neocortex-chat");
chat.agent.registerAction("OPEN_PRODUCT", (action) => openProduct(action.targetId));openProduct はあなた自身の関数です。キャラクターは、会話に合うタイミングでアクションを選び、そのアクションで何をするかはあなたのコードが決めます。
Webサイトのキャラクターのアイデア
- 製品ガイド。 3Dのコンフィギュレーターで、オプションを説明し、頼まれたら色を切り替えます。
- イベントの司会。 日程の質問に答え、訪問者を適切なステージへ案内します。
- 美術館やブランドのキャラクター。 アーカイブの物語を、自分の声で語ります。
- ゲームのランディングページ。 買う前に、訪問者がゲームのキャラクターと話せます。
より詳しくは、ユースケースのガイドで 3D Web ストアのAIショッピングガイドと バーチャルイベントのAI司会 を扱っています。
よくある問題
- マイクが始まらない。 ブラウザーは、録音の前に HTTPS とクリックかタップを要求します。HTTP のプレビューではなく、実際のドメインでテストしてください。
- エンドポイントから 401 または 403 が返る。
authorizeがnullを返したか、キャラクターのIDがcharactersの一覧にありません。 - キーがブラウザーに渡ってしまった。 クライアントのコードに決して渡さないでください。
NEOCORTEX_API_KEYを読むのは、サーバーのハンドラーだけであるべきです。
次のステップ
Webサイトではなくゲームエンジンで作るなら、Unity のゲームにAIキャラクターを追加する方法から始めてください。音声の仕組みを知りたいなら、AI NPC の音声パイプラインの仕組みを読んでください。このシリーズのすべてのチュートリアルは、AI NPC の作り方ガイドにまとめています。設定の全体は Web SDK のドキュメントにあります。
よくある質問
音声付きのAIキャラクターをサイトに追加するにはどうすればいいですか?
Neocortex Web SDK をインストールし、APIキーが外に出ないように小さなプロキシをサーバーに追加し、voice 属性を付けた neocortex-chat の要素をページに置きます。訪問者は入力するか話すかでき、キャラクターは声で答えます。
APIキーを公開せずに、AIチャットボットをサイトに置けますか?
はい。Neocortex Web SDK には、キーを保持し、話しかけてくる相手を確認し、指定したキャラクターだけを許可するサーバー用のハンドラーが含まれています。ブラウザーが通信するのは、あなた自身のエンドポイントだけです。
React、Vue、WordPress で動きますか?
チャットのUIは標準の Web Components でできているので、React、Vue、Svelte、Angular、素の HTML で動きます。Next.js、Express、Cloudflare Workers など、小さなサーバーのエンドポイントを動かせるサイトなら、プロキシを置けます。
Neocortex Web SDK の料金はかかりますか?
SDK は Apache-2.0 のオープンソースです。会話は Neocortex のプランの利用量に含まれます。
キャラクターはページ上で何かできますか?
はい。Neocortex のエディターでキャラクターのアクションを定義し、ページ側で各アクションのハンドラーを登録します。たとえば、製品を開く、ツアーを始める、特定のセクションまでスクロールするなどです。






