Claude Code 음성 에이전트 만들기: AssemblyAI Voice Agent API 워크숍

핵심 메시지

• AssemblyAI Voice Agent API는 음성인식(STT)·LLM·음성합성(TTS)을 하나로 묶어 제공해, 개발자가 세 모델을 따로 연결할 필요가 없다.
• 워크숍에서는 Claude Code에 API 문서 링크만 주고도 파이썬 백엔드와 HTML 프런트엔드를 스캐폴딩해 예약 음성 에이전트를 만든다.
• 백엔드는 API 키를 브라우저에 노출하지 않으려 임시 토큰을 발급하는 인증 흐름을 담당한다.
• progressive tool reveal 패턴으로 가용성 확인 후에만 예약 도구를 노출해, 에이전트의 환각과 잘못된 도구 호출을 줄인다.
• 도구 수를 최소화하고 턴 감지(최소/최대 침묵) 설정을 보수적으로 두는 것이 정확도와 사용자 경험에 더 유리하다.

쉽게 이해하기

AssemblyAI는 음성 모델 회사로, 오디오를 텍스트로 바꾸는 전사 모델을 만든다. 이번 워크숍의 주제인 Voice Agent API는 STT·LLM·TTS를 하나의 API로 수직 통합해 제공한다. 개발자가 음성-텍스트, 대형 언어 모델, 음성 합성 모델을 각각 설정·연결할 필요 없이, 회사가 오케스트레이션 전체를 담당한다. 에이전트를 외부 애플리케이션에 붙이는 대신, 애플리케이션을 에이전트 안에서 만든다는 발상이다.

라이브 빌드는 Claude Code만으로 진행됐다. 발표자는 API 문서 페이지 링크 하나를 Claude에 넘기고 "Voice Agent API 문서다. 임시 토큰을 발급하는 파이썬 백엔드와 그 백엔드를 쓰는 HTML 프런트엔드를 만들어라"고 지시했다. MCP 서버나 스킬, 별도의 프롬프트 마법 없이 기본 Claude Code가 문서를 크롤링해 백엔드·프런트엔드를 스캐폴딩했다.

백엔드가 임시 토큰을 발급하는 이유는 API 키를 브라우저(클라이언트)에 노출하지 않기 위해서다. 보안과 아키텍처 설계 차원의 표준적인 인증 흐름으로, 만든 애플리케이션을 안전하게 공유할 수 있게 해준다. 몇 개의 프롬프트만으로 로컬에서 동작하는 음성 에이전트 애플리케이션이 만들어졌고, 브라우저에서 마이크로 대화가 가능했다.

이어서 예약 생성 도구를 붙이고 UI에 도구 호출을 표시했다. 발표자가 강조한 설계 패턴은 'progressive tool reveal'이다. 가용성 확인 도구를 먼저 호출한 뒤 그 도구를 제거하고 예약 도구를 추가하는 식으로, 매 순간 하나의 도구만 노출한다. 이렇게 하면 에이전트가 가용성을 확인하지 않고 곧장 예약해 버리는 환각을 줄이고 도구 호출 정확도를 높일 수 있다.

지연시간과 사용자 경험에 대한 조언도 나왔다. 도구를 많이 붙여 최적화하기보다 도구 수를 줄이고 불필요한 단계를 없애는 단순화가 더 효과적이다. 턴 감지는 기본값이 최소 침묵 1초, 최대 침묵 3초로 보수적인데, 빠른 대화가 필요하면 최소 침묵을 500밀리초로 줄여 응답 시간을 절반으로 줄일 수 있지만 사용자가 천천히 말할 때 말을 끊을 위험이 커진다. 완성된 앱은 GitHub 저장소로 만들어 Railway로 배포해 공유할 수 있었다.

주요 인사이트

• 코딩 에이전트(Claude Code)는 단순히 모델에 문서를 주는 게 아니라 웹 검색으로 문서를 크롤링해 API 사용법을 스스로 파악하기 때문에, "음성 에이전트를 만들어줘" 수준의 한 줄 프롬프트로도 앱을 스캐폴딩한다.
• 발표자는 프롬프트 엔지니어링을 일부러 피하고 친구에게 문자 보내듯 지시한다 — Claude를 과하게 통제하면 오히려 한 작업에 과집중해 결과가 나빠질 수 있다고 본다.
• 지연시간은 도구를 많이 붙여 최적화하기보다, 도구 수를 줄이고 불필요한 단계를 없애는 단순화가 더 효과적이다.
• 턴 감지를 너무 공격적으로(짧은 침묵) 설정하면 응답은 빨라지지만 사용자가 천천히 말하거나 전화번호를 부를 때 말을 끊을 위험이 커진다 — 보수적 설정이 대체로 더 나은 결과를 낸다.

자주 묻는 질문

관련 AI 소식