웹사이트에 말하는 AI 캐릭터를 추가하는 방법
어떤 웹사이트에나 말하는 AI 캐릭터 추가하기: Neocortex Web SDK 설치, 서버에서 API 키 보관, 음성 채팅 요소 배치, 행동 처리.
Sercan AltundasFounder of Neocortex
· 7분 분량

웹사이트 캐릭터는 방문자가 자기 말로 대화할 수 있는 안내자, 진행자, 가게 도우미입니다. 일반 채팅 말풍선 대신 성격과 목소리가 있습니다. 이 가이드는 Neocortex Web SDK로 어떤 사이트에든 추가하는 방법을 보여 줍니다. 서버에 몇 줄, 페이지에 요소 하나, 그리고 캐릭터가 뭔가를 하게 하는 선택적 행동입니다.
만들 것
페이지의 캐릭터는 다음을 합니다.
- 타이핑하거나 말한 질문에 자기 목소리로 답합니다
- 여러분이 올린 지식 베이스를 통해 여러분의 콘텐츠를 압니다
- 제품을 열거나 투어를 시작하는 등 페이지에서 행동을 실행할 수 있습니다
- 여러분의 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에 마운트하세요. 로그인이 없는 사이트는 서명된 쿠키로 방문자마다 고정 id를 발급할 수 있습니다.
4단계: 페이지에 캐릭터 놓기
한 번 import "@neocortex-link/web/ui/auto"로 UI를 불러오세요(번들러가 없는 사이트라면 CDN 스크립트 태그로). 그다음 캐릭터가 나타날 곳에 요소를 놓으세요.
<neocortex-chat endpoint="/api/neocortex" character-id="your-character-id" voice></neocortex-chat>채팅에는 텍스트 상자와 마이크 입력이 있습니다. voice 속성은 음성 답변을 더합니다. 각 줄은 음성으로 스트리밍되며, 현재 줄이 재생되는 동안 다음 줄을 가져옵니다. 방문자가 말하는 동안 버튼을 누르고 있게 하려면 push-to-talk을 추가하고, 텍스트만 원하면 mic="false"를 쓰세요.
이 요소들은 표준 웹 컴포넌트이므로 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는 여러분의 함수입니다. 캐릭터는 대화에 행동이 맞는지 정하고, 그 행동이 무엇을 할지는 여러분의 코드가 정합니다.
웹사이트 캐릭터 아이디어
- 제품 안내. 3D 설정기에서 옵션을 설명하고, 요청하면 색을 바꿔 주는 안내자.
- 행사 진행자. 일정 질문에 답하고 방문자를 맞는 무대로 안내하는 진행자.
- 박물관이나 브랜드 캐릭터. 자기 목소리로 여러분의 아카이브 이야기를 들려주는 캐릭터.
- 게임 랜딩 페이지. 방문자가 구매 전에 게임의 캐릭터와 대화할 수 있는 곳.
3D 웹 스토어를 위한 AI 쇼핑 가이드와 가상 행사를 위한 AI 진행자 사용 사례 가이드에서 더 깊이 다룹니다.
자주 생기는 문제
- 마이크가 시작되지 않습니다. 브라우저는 HTTPS와, 녹음 전 클릭 또는 탭을 요구합니다. 일반 HTTP 미리보기가 아니라 실제 도메인에서 테스트하세요.
- 엔드포인트에서 401이나 403.
authorize가null을 돌려줬거나, 캐릭터 ID가characters목록에 없습니다. - 키가 브라우저에 들어갔습니다. 클라이언트 코드에 절대 넘기지 마세요. 서버 핸들러만
NEOCORTEX_API_KEY를 읽어야 합니다.
다음 단계
게임 엔진용으로는 유니티 게임에 AI 캐릭터를 추가하는 방법을 보세요. 음성 쪽을 이해하려면 AI NPC 음성 파이프라인의 동작 방식을 읽으세요. 시리즈의 모든 튜토리얼은 AI NPC 만들기 가이드에 있고, 전체 설정은 Web SDK 문서에 있습니다.
자주 묻는 질문
음성이 있는 AI 캐릭터를 웹사이트에 어떻게 추가하나요?
Neocortex Web SDK를 설치하고, API 키가 비공개로 남도록 작은 프록시를 서버에 추가한 뒤, voice 속성이 있는 neocortex-chat 요소를 페이지에 놓으세요. 방문자는 타이핑하거나 말할 수 있고, 캐릭터는 소리 내어 답합니다.
API 키를 노출하지 않고 사이트에 AI 챗봇을 넣을 수 있나요?
네. Neocortex Web SDK에는 키를 보관하고, 누가 말하는지 확인하고, 여러분이 나열한 캐릭터만 허용하는 서버 핸들러가 있습니다. 브라우저는 여러분 자신의 엔드포인트와만 대화합니다.
React, Vue, 워드프레스에서도 동작하나요?
채팅 UI는 표준 웹 컴포넌트로 만들어져 React, Vue, Svelte, Angular, 순수 HTML에서 동작합니다. Next.js, Express, Cloudflare Workers처럼 작은 서버 엔드포인트를 돌릴 수 있는 사이트라면 프록시를 호스팅할 수 있습니다.
Neocortex Web SDK는 무료인가요?
SDK는 Apache-2.0 오픈 소스입니다. 대화는 여러분의 Neocortex 요금제에 포함됩니다.
캐릭터가 페이지에서 일을 할 수 있나요?
네. Neocortex 편집기에서 캐릭터의 행동을 정의하고, 페이지에서 각 행동의 핸들러를 등록하세요. 예를 들어 제품 열기, 투어 시작, 특정 섹션으로 스크롤하기입니다.






