Skip to main content
vox.ai 음성 에이전트가 전화를 걸어 상대방과 대화하고, 모르는 내용이 나오면 API 도구 ask_brain으로 물어요. 질문은 중계 서버를 거쳐 내 AI 에이전트에게 전달되고, AI 에이전트가 보낸 답을 음성 에이전트가 자기 말로 상대방에게 전해요. AI 에이전트도 모르는 내용이면 터미널에서 나에게 먼저 물어본 뒤 답해요. 직접 만들기 전에 claude.tryvox.co 시연에서 먼저 체험해 보세요.

준비물

  • vox.ai 서버용 API 키: sk_...로 시작하는 서버용 키가 필요해요. 만드는 방법은 API 키에서 확인하세요.
  • 발신번호: 발신 도구 place_call에는 발신번호 from_number가 필수예요. 워크스페이스에 발신에 쓸 전화번호가 있어야 해요.
  • Node.js 18 이상: 로컬에서 중계 서버를 실행할 때 써요.
  • cloudflared: 로컬 중계 서버를 외부에서 부를 수 있게 공개 주소를 만들 때 써요. macOS에서는 brew install cloudflared로 설치하고, 다른 환경은 cloudflared 설치 안내를 따르세요.
  • AI 에이전트: Claude Code·Hermes·OpenClaw 가운데 하나를 준비하세요.
실제 발신에는 통화 요금이 들며, 요금과 동시 통화·운영 한도는 요금에서 확인하세요.

따라 만들기

1

중계 서버 띄우기

아래 코드를 relay.mjs로 저장하세요. 질문과 답을 메모리에만 두어 서버를 끄면 사라지는 시작용 서버예요.
relay.mjs
모든 요청은 Authorization: Bearer <RELAY_TOKEN> 헤더가 맞아야 하고, 다르면 401을 돌려줘요. 경로 세 가지는 다음과 같아요.
  • POST /ask/{call_id}: 음성 에이전트의 ask_brain 도구가 {question}을 담아 부르고, 답이 올 때까지 최대 50초 동안 기다려요.
  • GET /next/{call_id}?after=N: 내 AI 에이전트가 부르고, N번째 질문 {index, id, question}이 올 때까지 최대 50초 동안 기다려요.
  • POST /answer: 내 AI 에이전트가 {id, answer}를 담아 답을 보내요. 본문이 JSON이 아니거나 answer가 비면 400, 모르는 id면 404, 이미 답한 질문이면 409를 돌려줘요.
토큰을 정하고 중계 서버를 실행하세요.
실행하면 터미널에 relay on :8787이 출력돼요.
2

터널 열기

새 터미널을 열고 cloudflared로 로컬 중계 서버의 공개 주소를 만드세요. 중계 서버를 공개 서버에 올렸다면 터널 대신 그 주소를 쓰세요.
이 주소는 cloudflared를 다시 켤 때마다 바뀌어요. 실행하면 터미널에 https://<임의 이름>.trycloudflare.com 형태의 주소가 출력돼요.
3

내 AI 에이전트에 vox.ai 연결하기

사용하는 AI 에이전트 문서를 따라 vox.ai MCP 서버를 연결하세요.

Claude Code

claude mcp add 명령으로 vox.ai MCP 서버를 연결할 수 있어요.

Hermes

hermes mcp add 대화형 설정으로 vox.ai MCP 서버를 연결할 수 있어요.

OpenClaw

환경 변수와 openclaw.json으로 vox.ai MCP 서버를 연결할 수 있어요.
연결을 마치고 에이전트 목록을 물어보면 워크스페이스의 에이전트 목록이 조회돼요.
4

음성 에이전트 준비하기

처음 한 번만 실행하는 단계예요. 아래 지시문의 <터널 주소>와 <RELAY_TOKEN 값>을 바꿔 AI 에이전트에게 붙여 넣으세요.
준비가 끝나면 AI 에이전트가 만들어진 ask_brain 도구 ID와 「내 AI 비서」 에이전트 ID를 알려 줘요.
5

전화 걸기

전화를 걸 때마다 아래 지시문의 꺾쇠 자리를 채워 AI 에이전트에게 붙여 넣으세요. 답을 기다리는 동안 통화에서는 대기음이 흘러요.
통화 중 질문과 답이 터미널에 보이고, 통화가 끝나면 AI 에이전트가 질문·답·요약을 정리해 보여 줘요.

완성 확인

  • AI 에이전트 정리 결과: AI 에이전트가 정리한 내용에 받은 질문과 보낸 답이 있고, get_call 원문에 ask_brain 호출과 답을 전한 에이전트 발화가 있으면 정상이에요.
  • 중계 서버에서 직접 확인: 통화 중에 아래 명령을 실행하면 첫 질문이 보여요.

처음 막히는 곳

프롬프트에 그 질문을 상대에게 소리 내어 묻지 말라는 줄이 들어 있는지 확인하세요. 음성 에이전트 준비 지시문에는 이 문장이 기본으로 들어 있어요.
새로 만들지 말고 이미 있는 ask_brain 도구를 쓰거나 고치라고 AI 에이전트에게 요청하세요. 이전에 같은 이름으로 만든 도구가 워크스페이스에 남아 있기 때문이에요.
AI 에이전트에게 ask_brain 도구의 URL을 새 주소로 바꿔 달라고 요청하세요. cloudflared는 다시 켤 때마다 터널 주소가 바뀌어요.
ask_brain 도구의 Bearer 값이나 curl에 넣은 토큰이 중계 서버의 RELAY_TOKEN과 같은지 확인하세요. 토큰이 다르면 중계 서버가 요청을 거절해요.
상대에게 전할 내용을 전화 걸기 지시문의 brief에 넣으세요. 프롬프트가 먼저 인사하라고 해도, brief가 비어 있으면 음성 에이전트가 인사 전에 ask_brain부터 부르고 답이 올 때까지 말을 시작하지 않는 일이 있어요.
ask_brain 도구의 응답 대기 시간을 중계 서버 대기 시간인 50초보다 긴 60초로 유지하세요. 50초 안에 답이 없으면 음성 에이전트는 빈 answer와 안내 문구를 받고 말없이 같은 질문으로 ask_brain을 다시 불러요.

다음 단계

  • API 도구: 외부 서버를 부르는 도구 설정과 응답 대기 시간 다루기
  • 시스템 변수: 통화마다 그 통화 ID로 바뀌는 {{call_id}} 같은 변수 알아보기
  • MCP 도구: 전체 도구 목록과 안전한 실행 규칙 확인하기
  • 통화 중 맥락 넣기: 질문을 기다리지 않고 AI 에이전트가 먼저 알려 주고 싶을 때 맥락 전달하기