CLI 스크립팅 및 자동화

이 페이지는 ant CLI를 기반으로 구축된 작업 중심 워크플로를 다룹니다. 기본 플래그 및 출력 옵션에 대해서는 CLI 사용하기를 참조하세요.

API 리소스 버전 관리

CLI를 사용하여 스킬, 에이전트, 환경 또는 배포와 같은 API 리소스를 리포지토리에서 YAML 파일로 버전 관리하고 Claude API와 동기화된 상태로 유지할 수 있습니다.

1. 1

   에이전트 정의하기

   에이전트 정의를 summarizer.agent.yaml에 작성합니다:

   summarizer.agent.yaml

   

   name: Summarizer
   model: claude-opus-5
   system: |
     You are a helpful assistant that writes concise summaries.
   tools:
     - type: agent_toolset_20260401

2. 2

   에이전트 생성하기

   ant beta:agents create < summarizer.agent.yaml

   

   Output

   

   {
     "id": "agent_011CYm1BLqPXpQRk5khsSXrs",
     "version": 1,
     "name": "Summarizer",
     "model": "claude-opus-5"
     /* ... */
   }

   응답의 id를 기록해 두세요. 이후 단계에서 세션 생성 명령에 전달하게 됩니다.

3. 3

   환경 정의하기

   세션은 환경에서 실행되며, 환경은 세션이 실행되는 샌드박스를 정의합니다. 환경 정의를 summarizer.environment.yaml에 작성합니다:

   summarizer.environment.yaml

   

   name: summarizer-env
   config:
     type: cloud
     networking:
       type: unrestricted

4. 4

   환경 생성하기

   ant beta:environments create < summarizer.environment.yaml

   

   Output

   

   {
     "id": "env_01595EKxaaTTGwwY3kyXdtbs",
     "name": "summarizer-env"
     /* ... */
   }

   응답의 id를 기록해 두세요. 이후 단계에서 세션 생성 명령에 전달하게 됩니다.

5. 5

   세션 시작하기

   이전 출력의 에이전트 id와 환경 id를 세션 생성 명령에 붙여 넣습니다:

   ant beta:sessions create \
     --agent agent_011CYm1BLqPXpQRk5khsSXrs \
     --environment-id env_01595EKxaaTTGwwY3kyXdtbs \
     --title "Summarization task"

   

   Output

   

   {
     "id": "session_01JZCh78XvmxJjiXVy3oSi7K",
     "status": "running"
     /* ... */
   }

6. 6

   사용자 메시지 보내기

   이전 출력의 세션 id를 --session-id에 복사합니다:

   ant beta:sessions:events send \
     --session-id session_01JZCh78XvmxJjiXVy3oSi7K \
     --event '{type: user.message, content: [{type: text, text: "Summarize the benefits of type safety in one sentence."}]}'

   
7. 7

   대화 읽기

   --transform은 나열된 각 이벤트에 대해 실행되므로, 모든 메시지의 텍스트가 순서대로 출력됩니다. --format auto는 list 명령이 터미널에서 기본적으로 여는 대화형 탐색기를 재정의합니다:

   ant beta:sessions:events list \
     --session-id session_01JZCh78XvmxJjiXVy3oSi7K \
     --transform 'content.0.text' --format auto --raw-output

   

   Output

   

   Summarize the benefits of type safety in one sentence.
   Type safety catches errors at compile time rather than runtime, reducing bugs, improving code clarity, enabling better tooling support, and making codebases easier to maintain and refactor with confidence.

스크립팅 패턴

CLI는 표준 셸 도구와 조합하여 사용할 수 있도록 설계되었습니다.

list 출력을 두 번째 명령으로 연결하기

list 엔드포인트에서 --transform id --raw-output을 사용하면 한 줄에 하나의 ID만 출력되므로, head 및 xargs와 같은 표준 도구를 바로 적용할 수 있습니다. 첫 번째 결과를 캡처한 다음 후속 명령에 전달합니다:

FIRST_AGENT=$(ant beta:agents list --transform id --raw-output | head -1)

ant beta:agents:versions list \
  --agent-id "$FIRST_AGENT" \
  --transform "{version,created_at}" --format jsonl

오류 검사하기

--transform-error 및 --format-error 플래그는 오류 응답에 동일한 필터링을 적용합니다. --raw-output은 오류에 적용되지 않으므로, 따옴표 없는 스칼라 값을 얻으려면 --format-error yaml을 사용하세요. 오류 메시지만 추출합니다:

ant beta:agents retrieve --agent-id bogus \
  --transform-error error.message --format-error yaml 2>&1

GET "https://api.anthropic.com/v1/agents/bogus?beta=true": 404 Not Found
Agent not found.

Claude Code에서 CLI 사용하기

Claude Code는 별도 설정 없이 ant CLI를 사용할 수 있습니다. CLI가 설치되고 인증되어 있으면 Claude Code에 API 리소스를 직접 조작하도록 요청할 수 있습니다. 예를 들어:

• "최근 에이전트 세션을 나열하고 어떤 세션에서 오류가 발생했는지 요약해 줘."
• "./reports에 있는 모든 PDF를 Files API에 업로드하고 결과 ID를 출력해 줘."
• "세션 session_01...의 이벤트를 가져와서 에이전트가 어디에서 막혔는지 알려 줘."

Claude Code는 ant를 셸에서 실행하고, 구조화된 출력을 파싱하며, 결과를 바탕으로 추론합니다(별도의 통합 코드가 필요하지 않습니다).

CLI 자격 증명으로 curl 요청 인증하기

curl 또는 다른 HTTP 클라이언트로 API를 호출하는 스크립트는 정적 API 키 대신 ant auth login으로 저장된 자격 증명을 사용할 수 있습니다. OAuth 액세스 토큰은 Authorization 헤더에 bearer 토큰으로 들어가며, x-api-key 헤더는 정적 API 키 전용입니다.

ant auth print-credentials --access-token은 활성 프로필의 액세스 토큰을 출력하며, 토큰이 만료되었거나 만료가 임박한 경우 먼저 갱신합니다:

curl https://api.anthropic.com/v1/messages \
  -H "Authorization: Bearer $(ant auth print-credentials --access-token)" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "hi"}]
  }'

ant auth status를 실행하여 어떤 조직과 워크스페이스에 로그인되어 있는지 확인하세요. 환경 변수가 로그인을 재정의하고 있는 경우 경고를 표시합니다.