설치하고 로그인하기
npm으로 설치하세요. Homebrew를 쓰면brew install vox-public/tap/vox로 설치할 수 있어요.
연결 확인
로그인한 계정·워크스페이스와 원격 에이전트 목록을 확인하세요.에이전트 만들거나 가져오기
빈 프로젝트 폴더를 만들고 그 안에서 시작하세요. 일반적인 대화형 업무는 Single 에이전트와 메뉴얼로 구성하세요. 현재 CLI는 유형을 생략하면 Flow로 만들기 때문에single_prompt를 명시해요.
새 에이전트를 만들 때는 아래 명령을 실행하세요.
agents/main/agent.json에서 에이전트 설정을, agents/main/manuals/reservation/manual.json에서 응대 절차를 작성하세요.
기존 에이전트를 가져올 때는 빈 폴더에서 아래 명령을 실행하세요. pull이 프로젝트를 함께 만들어요. <agent-id>에는 목록에서 확인한 ID를 넣으세요.
검증하고 저장하기
먼저 고친 파일을 검증하세요.reservation은 앞에서 만든 메뉴얼 이름이에요. 가져온 에이전트는 vox manual list --agent main에서 이름을 확인해 바꾸세요. 메뉴얼을 쓰지 않으면 manual 명령은 건너뛰세요.
agent push는 에이전트 설정만 저장하므로 메뉴얼은 따로 저장해요.
평가 정의를 저장하고 실행하기
vox eval로 유닛 테스트와 시나리오 테스트를 JSON 파일로 만들고 서버에서 실행할 수 있어요. 종류는 --kind로 골라요.
init이 만든 골격을 채우세요. 유닛 테스트의 messages는 통화·채팅 기록의 대화와 같은 모양이라, 기록을 붙여 넣고 확인할 지점까지 자르면 돼요. 항목의 다른 키(start_at 등)는 무시하지만, eval 안의 키 이름이 틀리면 저장하지 않아요. 마지막 항목 하나에만 eval을 붙이고, 그 항목이 기대하는 다음 행동이에요. 기대하는 답이면 agent, 기대하는 도구 호출이면 tool_call_invocation을 마지막에 두세요. 판정은 expected_behavior 문장을 기준으로 하므로, 도구 호출을 기대할 때는 어떤 도구를 어떤 값으로 불러야 하는지 그 문장에 적으세요. 이력의 tool_call_invocation 바로 다음에는 그 결과인 tool_call_result가 와야 해요.
reservation-test.json
validate는 저장하지 않고 파일만 검사해요. 형식이 틀린 파일은 저장하지 않아요. 형식은 맞지만 규칙에 어긋난 유닛 테스트는 실행할 수 없는 초안으로 저장되고 종료 코드 1을 돌려줘요. validation.issues의 위치를 보고 고친 뒤 update하세요.
run은 서버에 저장된 에이전트 설정으로 실행하고 끝날 때까지 기다려요. 로컬에서 고친 설정은 먼저 vox agent push로 저장하세요. 요청 한 번에 반복 횟수를 합쳐 100건까지 실행할 수 있어요. --no-wait를 붙이면 배치 ID와 실행 ID만 받고 끝나요.
status는 진행 상태라서 completed는 결과가 나왔다는 뜻일 뿐이에요. 판정은 result에서 확인하세요. passed는 통과, failed는 기대와 다름, error는 실행이나 판정 중 오류예요. runs list는 --status와 --result로 거를 수 있고, 목록 명령은 --sort asc|desc로 순서를 바꿀 수 있어요. 기본은 최신순이에요.
기존 vox agent test는 로컬 정적 검사예요. 서버에서 평가하려면 vox eval을 쓰세요.
버전 저장하고 게시하기
저장을 마치면 원격의 현재 설정으로 버전을 만드세요.v1을 저장 결과의 버전으로 바꾸세요.
push는 현재 설정 저장, version save는 버전 저장, promote는 프로덕션 지정이에요. 버전 관리에서 반영 범위를 확인할 수 있어요.
코딩 에이전트와 함께 쓰기
vox init은 Claude Code용 .claude/skills/vox-ai/SKILL.md와 Codex용 .codex/skills/vox-ai/SKILL.md를 만들어요. 같은 프로젝트에서 코딩 에이전트를 열고 작업을 요청하세요.
vox guide coding-agent --brief 출력을 지침으로 전달하세요. 로컬 스킬은 CLI 작업 지침이고 플러그인의 업무별 스킬과는 별도예요. 갱신과 CI 인증은 CLI 명령에서 확인하세요.
문제가 생겼을 때
로그인이 만료됐거나 인증 오류가 나요
로그인이 만료됐거나 인증 오류가 나요
vox auth login으로 다시 로그인한 뒤 vox auth whoami로 대상을 확인하세요. 저장된 다른 계정으로 바꾸려면 vox auth switch를 실행하세요.CI에서 브라우저를 열 수 없어요
CI에서 브라우저를 열 수 없어요
CI 인증 설정에 따라 액세스 토큰과 워크스페이스를 환경 변수로 지정하세요.
CLI를 업데이트했는데 스킬 지침이 예전 그대로예요
CLI를 업데이트했는데 스킬 지침이 예전 그대로예요
vox agent skills refresh를 실행하세요. CLI가 관리하는 지침 파일을 최신 템플릿으로 갱신해요.관련 문서
- CLI 명령: 명령 목록, JSON 출력, 인증과 CI
- 에이전트 버전 관리: 저장과 프로덕션 지정
- 메뉴얼: 업무별 응대 절차 작성