많은 웹사이트 AI 데모들은 질문에 답하는 수준에서 멈춥니다.

어시스턴트는 무언가가 어디에 있는지 설명할 수는 있지만, 실제로 당신을 그곳으로 데려다주지는 못합니다. 설정을 열라고 말할 수는 있지만, 실제로 설정을 열지는 못합니다. 양식을 작성해 달라고 요청할 수는 있지만, 양식을 건드리지는 못합니다.

그것이 바로 제가 Telnyx AI Assistant 클라이언트 사이드 도구(client-side tools)를 통해 보여주고 싶었던 차이점입니다.

Telnyx 코드 예제는 여기 있습니다:

https://github.com/team-telnyx/telnyx-code-examples/tree/main/ai-assistant-client-side-tools-nextjs

과정은 샘플을 클론(clone)하고, Telnyx AI Assistant에서 동일한 도구 이름과 JSON 스키마(JSON schemas)를 구성한 다음, 브라우저 앱에 공개 어시스턴트 ID를 설정하고, 웹사이트 호출 버튼을 통해 UI 액션을 테스트하는 것입니다.

아이디어

클라이언트 사이드 도구(Client-side tools)를 사용하면 Telnyx AI Assistant가 음성 또는 채팅 대화 중에 브라우저 내에서 미리 정의된 JavaScript 함수를 호출할 수 있습니다.

사소하게 들릴 수 있지만, 이는 데모를 완전히 바꿉니다.

다음과 같이 말하는 대신:

AI Assistants 페이지로 이동하여 Create Assistant를 클릭하세요.

어시스턴트는 다음과 같이 호출할 수 있습니다:

navigate_to_section
open_create_assistant_modal

이 함수들은 일반적인 React 상태 업데이트(state updates)이기 때문에 브라우저가 즉시 업데이트됩니다.

내가 만든 것

이 샘플은 PolarForge AI라는 가상의 SaaS 대시보드입니다. Next.js, React, TypeScript, 그리고 Tailwind CSS로 구축되었습니다.

이 대시보드는 사이드바, 여러 대시보드 섹션, 라이트 및 다크 테마, AI Assistants 페이지, Create Assistant 모달, 그리고 모든 도구 호출을 기록하는 액티비티 패널을 갖추고 있습니다.

어시스턴트는 다섯 가지 도구를 사용할 수 있습니다:

• set_theme
• navigate_to_section
• open_create_assistant_modal
• get_form_state
• update_assistant_form

흥미로운 것은 get_form_state인데, 이는 현재의 React 상태(state)를 읽어야 하기 때문입니다. 단순히 하드코딩된 객체를 반환하는 것이 아닙니다. 만약 모달이 열려 있고 양식에 어시스턴트 이름이 "Enterprise Concierge"라고 되어 있다면, 도구는 해당 가시적인 상태를 반환합니다.

Webhook 대신 클라이언트 사이드(Client-Side)를 사용하는 이유

Webhook 도구는 여전히 유용합니다. 만약 어시스턴트가 계정을 생성하거나, 카드를 결제하거나, CRM 레코드를 업데이트하거나, 권한이 있는 자격 증명(privileged credentials)으로 무언가를 호출해야 한다면, 그것은 백엔드(backend)에서 처리되어야 합니다.

하지만 많은 웹사이트 동작들은 로컬(local)에서 이루어집니다:

• 다크 모드로 전환
• 모달(modal) 열기
• 싱글 페이지 애플리케이션(single-page app) 내부 탐색
• 보이는 양식(form) 채우기
• 페이지 상태(page state) 읽기
• 브라우저가 이미 인증된 상태로 호출할 수 있는 API 호출

이러한 부분이야말로 클라이언트 사이드(client-side) 도구가 더 적합한 영역입니다. 어시스턴트가 단순히 React 상태(state)를 변경하기 위해 백엔드 Webhook을 사용할 필요는 없습니다.

통합 (The Integration)

이 앱은 @telnyx/ai-agent-lib를 사용합니다:

<TelnyxAIAgentProvider agentId={agentId}>
  <ToolRegistrar executeTool={executeTool} />
  <TelnyxWidget />
...

React 내부에서 도구는 다음과 같이 등록됩니다:

client.registerClientTool("navigate_to_section", async (args) => {
  return executeTool("navigate_to_section", args);
});

이에 대응하는 도구 정의(tool definitions)는 여전히 Telnyx AI Assistant에 존재해야 합니다. 이름과 JSON 스키마(JSON schemas)는 브라우저가 등록하는 것과 일치해야 합니다.

데모 순간 (The Demo Moment)

데모의 깔끔한 버전은 다음과 같습니다:

사용자: 다크 모드로 전환해줘
어시스턴트: set_theme 호출
페이지: 다크 모드로 변경
...

이것이 증거입니다. 어시스턴트는 단순히 앱에 대해 이야기하는 것이 아닙니다. 승인된 브라우저 기능을 통해 앱을 제어하고 있는 것입니다.

보안 경계 (Security Boundary)

브라우저는 Telnyx API 키를 받지 않습니다.

샘플은 AI Agent Lib 연결을 위해 공개된 NEXT_PUBLIC_* 설정을 사용합니다. 어시스턴트를 프로비저닝(provision)하거나 Telnyx REST API를 호출해야 한다면, 보안이 확보된 서버 사이드(server-side) 환경이나 Telnyx Portal을 통해 수행하십시오.

또한 샘플은 모든 도구 호출(tool call)을 검증합니다. 알 수 없는 섹션은 실패합니다. 알 수 없는 양식 필드(form fields)는 실패합니다. 유효하지 않은 음성이나 언어는 실패합니다. 모달이 닫혀 있는 동안 양식을 업데이트하려고 하면 실패합니다.

이것이 제가 프로덕션 앱(production app)에서 유지하고 싶은 형태입니다. 작고 명시적인 도구, 엄격한 검증, 그리고 클라이언트 사이드 코드에 권한이 있는 비밀 정보(privileged secrets)를 두지 않는 것입니다.

리소스 (Resources)

리소스 (Resources)

• 코드 예제: https://github.com/team-telnyx/telnyx-code-examples/tree/main/ai-assistant-client-side-tools-nextjs
• 클라이언트 측 도구 문서: https://developers.telnyx.com/docs/inference/ai-assistants/client-side-tools
• AI 에이전트 라이브러리 (AI Agent Lib): https://www.npmjs.com/package/@telnyx/ai-agent-lib
• Telnyx 릴리스 노트: https://telnyx.com/release-notes/client-side-tools-ai-assistants