Update to vox.ai

{
  "description": "vox.ai 음성 에이전트가 외부 API로 실제 조회·예약·접수·전달을 수행하도록 연동 계약과 실패 대응을 설계할 때 사용한다.",
  "included_files": [],
  "name": "tool-integration-design",
  "skill_md_contents": "---\nname: tool-integration-design\ndescription: \"vox.ai 음성 에이전트가 외부 API로 실제 조회·예약·접수·전달을 수행하도록 연동 계약과 실패 대응을 설계할 때 사용한다.\"\nmetadata:\n  product: vox.ai\n  layer: general\n  status: stable\n---\n\n# tool-integration-design\n\n## 완료를 정의한다\n사용자가 원하는 외부 결과와 API의 응답 의미를 먼저 맞춘다. 요청 수락·작업 접수·전송, 고객의 수신·실제 이용 가능, 업무 완료는 서로 다른 상태다. 응답 계약이 확인해 주는 단계만 완료로 보고하고, 내부 추출 결과 저장을 외부 작업 성공으로 대체하지 않는다.\n\n실패, 미수신, 또는 고객이 결과를 쓸 수 없는 경우에는 실제 지원되는 대체 경로를 안내한다. 대체 전송·전환 등 부작용을 실행할 때는 계약상 필요한 동의를 확인한다. 자동 재전송 정책이나 확인되지 않은 화면 조작 경로를 만들지 않는다. 필요한 fallback이 계약에 없으면 그 한계를 표시하고 사용자와 다음 선택을 정한다.\n\n## 설계에 필요한 근거\nendpoint·method·인증 방식·필수 입력·응답/오류 예·부작용·지원되는 중복 판별/결과 조회를 API 문서나 사용자의 명시 정보로 확인한다. 부족한 입력은 질문하되 비밀값을 먼저 요구하거나 반복 출력하지 않는다. 필요한 인증값은 사용자가 직접 준 것만 `save_tool`로 저장하고, 이후 조회 응답에서는 마스킹된다.\n\n입력값의 출처를 고객 발화, 사전 정보, 고정 설정, 이전 도구 결과로 구분한다. 반환값은 다음 판단과 사용자 설명에 필요한 필드를 중심으로 설계한다. 도구 설명에는 언제 호출하고 언제 호출하지 않을지, 오류 시 무슨 말을 할지 적는다.\n\n## 실행 위치\n음성 agent가 통화 중 호출하는 도구와 코파일럿이 agent를 관리하는 MCP 도구를 구분한다. 부작용이 있는 동작은 실행 주체·시점을 확인하고, postCall 결과 필드나 prompt 복사만으로 외부 실행이 생긴다고 가정하지 않는다. 결과가 pending이면 완료로 보고하지 않는다. 브라우저 동작이 필요한 경우 제품이 제공하는 실행 환경부터 확인한다. vox.ai에서 실제 지원하는 도구 종류·스키마로 표현 가능한지 확인한다. 통화 중 상태와 postCall 결과를 나누는 기준은 [통화 결과 설계](../post-call-result-design/SKILL.md)를 따른다.\n\n반복·불명 결과의 처리와 인증 오류를 정상 결과와 구분한다. 외부 실행이 불명일 때 새 요청을 보내는 정책을 임의로 만들지 않는다.\n\n저장·연결은 [connect-agent-tools](../connect-agent-tools/SKILL.md), 실제 오류는 [troubleshoot-agent-tool](../troubleshoot-agent-tool/SKILL.md)로 이어간다.\n\nFlow 업무에서는 [Flow 업무 계약](../../references/flow-business-contract.md)의 재조회·등록값 비교·문항별 기록·시험 입력 계약을 함께 적용한다.\n"
}