CLI, SDK 및 라이브러리ant CLI

CLI 스크립팅 및 자동화

API 리소스를 YAML로 버전 관리하고, 스크립트에서 ant CLI 명령어를 연결하며, Claude Code에서 리소스를 조작합니다.

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

API 리소스 버전 관리

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

이러한 리소스에 대한 자세한 내용은 Managed Agents를 참조하세요.

에이전트 정의

에이전트 정의를 summarizer.agent.yaml에 작성하세요:

summarizer.agent.yaml

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

에이전트 생성
ant beta:agents create < summarizer.agent.yaml
Output
{ "id": "agent_011CYm1BLqPXpQRk5khsSXrs", "version": 1, "name": "Summarizer", "model": "claude-sonnet-4-6" /* ... */ }
응답에서 id를 기록해 두세요. 이후 단계에서 세션 생성 명령어에 전달하게 됩니다.
summarizer.agent.yaml을 리포지토리에 체크인하고 CI 파이프라인에서 API와 동기화 상태를 유지하세요. 업데이트 명령어에는 에이전트 ID와 현재 버전이 플래그로 필요합니다:
CLI
ant beta:agents update --agent-id agent_011CYm1BLqPXpQRk5khsSXrs --version 1 < summarizer.agent.yaml
환경 정의
세션은 환경에서 실행되며, 환경은 세션이 실행되는 샌드박스를 정의합니다. 환경 정의를 summarizer.environment.yaml에 작성하세요:
summarizer.environment.yaml
name: summarizer-env config: type: cloud networking: type: unrestricted
환경 생성
ant beta:environments create < summarizer.environment.yaml
Output
{ "id": "env_01595EKxaaTTGwwY3kyXdtbs", "name": "summarizer-env" /* ... */ }
응답에서 id를 기록해 두세요. 이후 단계에서 세션 생성 명령어에 전달하게 됩니다.
summarizer.environment.yaml을 리포지토리에 체크인하고 CI 파이프라인에서 API와 동기화 상태를 유지하세요. 업데이트 명령어에는 환경 ID가 플래그로 필요합니다:
CLI
ant beta:environments update --environment-id env_01595EKxaaTTGwwY3kyXdtbs < summarizer.environment.yaml

세션 시작

이전 출력에서 얻은 에이전트 id와 환경 id를 세션 생성 명령어에 붙여넣으세요:

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

Output

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

사용자 메시지 전송

이전 출력의 세션 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."}]}'

대화 읽기
--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.
```
세션이 실행되는 동안 실시간으로 확인하려면 ant beta:sessions:events stream --session-id session_01JZCh78XvmxJjiXVy3oSi7K를 사용하세요. 이벤트는 도착하는 대로 stdout에 기록됩니다.

스크립팅 패턴

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

Output

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를 셸에서 실행하고, 구조화된 출력을 파싱하며, 결과를 바탕으로 추론합니다(별도의 통합 코드가 필요하지 않습니다).

Was this page helpful?

CLI, SDK 및 라이브러리ant CLI

CLI 스크립팅 및 자동화

API 리소스를 YAML로 버전 관리하고, 스크립트에서 ant CLI 명령어를 연결하며, Claude Code에서 리소스를 조작합니다.

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

API 리소스 버전 관리

이러한 리소스에 대한 자세한 내용은 Managed Agents를 참조하세요.

에이전트 정의

에이전트 정의를 summarizer.agent.yaml에 작성하세요:

summarizer.agent.yaml

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

에이전트 생성
ant beta:agents create < summarizer.agent.yaml
Output
{ "id": "agent_011CYm1BLqPXpQRk5khsSXrs", "version": 1, "name": "Summarizer", "model": "claude-sonnet-4-6" /* ... */ }
응답에서 id를 기록해 두세요. 이후 단계에서 세션 생성 명령어에 전달하게 됩니다.
summarizer.agent.yaml을 리포지토리에 체크인하고 CI 파이프라인에서 API와 동기화 상태를 유지하세요. 업데이트 명령어에는 에이전트 ID와 현재 버전이 플래그로 필요합니다:
CLI
ant beta:agents update --agent-id agent_011CYm1BLqPXpQRk5khsSXrs --version 1 < summarizer.agent.yaml
환경 정의
세션은 환경에서 실행되며, 환경은 세션이 실행되는 샌드박스를 정의합니다. 환경 정의를 summarizer.environment.yaml에 작성하세요:
summarizer.environment.yaml
name: summarizer-env config: type: cloud networking: type: unrestricted
환경 생성
ant beta:environments create < summarizer.environment.yaml
Output
{ "id": "env_01595EKxaaTTGwwY3kyXdtbs", "name": "summarizer-env" /* ... */ }
응답에서 id를 기록해 두세요. 이후 단계에서 세션 생성 명령어에 전달하게 됩니다.
summarizer.environment.yaml을 리포지토리에 체크인하고 CI 파이프라인에서 API와 동기화 상태를 유지하세요. 업데이트 명령어에는 환경 ID가 플래그로 필요합니다:
CLI
ant beta:environments update --environment-id env_01595EKxaaTTGwwY3kyXdtbs < summarizer.environment.yaml

세션 시작

이전 출력에서 얻은 에이전트 id와 환경 id를 세션 생성 명령어에 붙여넣으세요:

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

Output

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

사용자 메시지 전송

이전 출력의 세션 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."}]}'

대화 읽기
--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.
```
세션이 실행되는 동안 실시간으로 확인하려면 ant beta:sessions:events stream --session-id session_01JZCh78XvmxJjiXVy3oSi7K를 사용하세요. 이벤트는 도착하는 대로 stdout에 기록됩니다.

스크립팅 패턴

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

list 출력을 두 번째 명령어로 연결

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

오류 검사

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

Output

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

Claude Code에서 CLI 사용

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

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

Was this page helpful?