문서와
대화하세요

script 태그 하나로 문서에 음성 버튼이 생깁니다. Cartesia Managed Agent가 페이지를 검색하고, 소리 내어 답하고, 인용한 섹션으로 페이지를 스크롤합니다.
GitHub에서 보기
Client tools와 Tools 두 페이지로 된 데모 문서 사이트에 음성 패널이 열려 있습니다. 방문자가 클라이언트 도구 결과의 최대 크기를 물었고, 에이전트가 최대 4096바이트라고 답했으며, 인용된 섹션이 화면에 스크롤되어 초록색으로 표시되어 있습니다

스크린샷. 로컬에서 실행 중인 템플릿입니다.

모델
ink-2, sonic-3.6
언어
영어, 스페인어, 프랑스어, 힌디어, 일본어
라이선스
Apache-2.0
기술 스택
HonoNode.jsWeb ComponentsesbuildBM25 or OpenAI embeddings
Cartesia 제품
Managed AgentsInk 2Sonic 3.6

하는 일

위젯은 어떤 사이트에서든 작동하며 다른 라이브러리가 필요 없습니다. 서버는 검색 인덱스를 로컬 파일에 저장하는 작은 Node 앱입니다. 검색은 기본으로 키워드를 비교합니다. OpenAI 키가 있으면 의미로 비교하므로, 문서와 다른 표현으로 한 질문도 더 잘 처리합니다. 다시 인덱싱하면 바뀐 페이지만 처리합니다.

직접 실행하기

  1. 데모 실행

    Node 22.22 이상에서 아래 명령어를 실행하고 http://localhost:4512를 연 뒤 Ask the docs, Start talking 순서로 누르세요. 데모 사이트는 docs.cartesia.ai의 두 페이지를 복사한 것입니다.

    npx degit cartesia-ai/cookbook/examples/docs-voice-widget docs-voice-widget
cd docs-voice-widget
# add CARTESIA_API_KEY
cp .env.example .env.local
npm install
# creates the agent and its two tools, saves the ids
npm run setup:agent
# indexes content/*.md into data/index.json
npm run ingest
npm run dev

    환경 변수
    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
    문서 사이트의 origin, 쉼표로 구분
    PUBLIC_URL, TRUST_PROXY
    프록시 뒤에서 사용. TRUST_PROXY=1이면 프록시가 덧붙인 주소를 기준으로 요청을 제한

  2. 내 문서 색인

    .md나 .mdx 파일 폴더라면 npm run ingest -- ./my-docs --base-url /docs/를 실행하고, 운영 중인 사이트라면 사이트맵 URL과 함께 npm run ingest -- --sitemap을 실행하세요.

  3. script 태그 추가

    Node 22.22 이상을 실행할 수 있는 호스트에 서버를 배포하고, 서버의 widget.js를 가리키는 script 태그 하나를 추가한 뒤, ALLOWED_ORIGINS를 문서 사이트의 origin으로 설정하세요.

코딩 에이전트로 만들기

어디서 시작하고 무엇을 먼저 읽어야 하는지 코딩 에이전트에게 알려 주는 프롬프트입니다.

프롬프트

Claude CodeCursorCodex

Add a voice assistant to my documentation site with a Cartesia Managed Agent. Start from https://github.com/cartesia-ai/cookbook/tree/main/examples/docs-voice-widget 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://www.cartesia.ai/agent-quickstart.md to get one.

작동 방식

script 태그cartesia-docs-agent 웹 컴포넌트를 불러옴
Ink 2방문자의 질문을 들음
search_docs내 서버에서 키워드나 임베딩으로 섹션 순위를 매기는 클라이언트 도구
show_source인용한 섹션으로 스크롤하고 색을 입힘
Sonic 3.6두세 문장으로 답함

이렇게 만든 이유

검색은 방문자의 브라우저에서 실행됩니다

Cartesia는 공개 HTTPS 주소에 있는 도구만 호출합니다. 클라이언트 도구는 방문자의 브라우저에서 실행되고 브라우저가 질문을 서버로 넘기므로, 데모는 터널 없이 localhost에서 작동합니다.

결과는 4,096바이트 이하

Cartesia는 4,096바이트가 넘는 클라이언트 도구 결과를 거부합니다. server/search.ts는 섹션 순위를 매기고, 현재 페이지에 약간의 가산점을 준 뒤, 상위 네 개를 3,800바이트 이하의 결과로 묶습니다.

실제로 계정을 지키는 것은 요청 제한입니다

서버는 Origin 헤더를 확인해 다른 사이트를 막지만, 스크립트는 어떤 헤더든 보낼 수 있습니다. 계정을 지키는 것은 IP 주소당 1분에 4개, 1시간에 30개라는 토큰 한도입니다.

원하는 대로 바꾸기

프롬프트와 도구

scripts/agent-config.ts를 수정한 뒤 npm run setup:agent -- --force를 실행하세요. 새 에이전트와 새 도구 두 개가 만들어지고 CARTESIA_TOOL_IDS를 덮어쓰므로, 먼저 이전 id를 복사해 두었다가 play.cartesia.ai에서 이전 에이전트와 도구를 삭제하세요. 도구 이름은 widget/src/tools.ts에도 있으니 둘 다 바꾸세요.

언어

설정 전에 AGENT_LANGUAGE를 es, fr, hi, ja 중 하나로 설정하세요. 프롬프트는 이미 방문자의 언어로 답하도록 되어 있습니다.

벡터 저장소

색인을 읽고 쓰는 파일은 server/store.ts 하나뿐입니다. 섹션 수천 개로 부족해지면 pgvector나 SQLite로 바꾸세요.

Cartesia로 전환하는 팀들과 함께하세요

Artificial Analysis

1위

Artificial Analysis의 Speech Arena 및 Speech to Text 리더보드에서

자주 묻는 질문

다른 사이트가 내 위젯과 API 키를 쓸 수 있나요?

아니요. ALLOWED_ORIGINS에 적은 사이트와 서버 자체 주소만 통화를 시작할 수 있습니다. API 키는 서버에 남고, 브라우저는 60초 뒤 만료되며 에이전트 통화에만 쓰이는 토큰을 받습니다.

Cartesia에 내장된 지식 베이스로는 안 되나요?

지식 베이스로도 문서를 바탕으로 답할 수 있습니다. 이 템플릿은 내 서버에서 검색하므로 각 결과에 페이지 링크와 섹션이 담기고, 위젯은 이를 이용해 그 섹션으로 스크롤합니다.

Docusaurus, Mintlify, Nextra에서도 작동하나요?

네. script 태그를 추가할 수 있는 곳이라면 어디서든 됩니다. 섹션 링크가 제목과 맞도록 사이트의 사이트맵으로 인덱싱하세요. 위젯은 사이트의 다크 모드나 방문자의 OS 설정을 따릅니다.

왜 다른 페이지 링크를 누르면 통화가 끝나나요?

통화는 페이지 안에서 진행되는데, 여러 페이지로 된 사이트는 이동할 때 페이지를 새로 불러옵니다. 그래서 통화 중에는 다른 페이지에 있는 출처가 새 탭에서 열립니다.

방문자의 통화가 녹음되나요?

네. Cartesia는 모든 에이전트 통화의 오디오와 기록을 녹음합니다. 방문자에게 알리고, 필요 없는 통화는 Cartesia API로 삭제하세요.

이 템플릿의 단계별 가이드가 있나요?

네. 레시피에서 코드를 단계별로 살펴보고, README에서 설정, 환경 변수, 배포를 다루며, 클라이언트 도구 문서에서 Cartesia 쪽 동작을 설명합니다.

쿡북 더 보기

전체 보기
말하기 연습 파트너. 외국어 연습

다섯 개 언어로 하는 역할극. 한 마디마다 교정해 줍니다.

프런트 데스크. 전화 접수원

전화를 받고, 시간을 예약하고, 통화를 기록합니다.

오늘 시작하세요

전문가와 상담하세요.

팀원과 연결해 Cartesia가 세계적 수준의 음성 경험을 만드는 데 어떻게 도움이 되는지 알아보세요.

영업팀 문의

개발을 시작하세요.

API로 모델을 사용하고 몇 분 만에 음성 에이전트를 프로덕션에 배포하세요.

Cartesia 사용해 보기