CLI、SDK 與函式庫ant CLI

CLI 指令碼與自動化

將 API 資源以 YAML 進行版本控制、在指令碼中串接 ant CLI 命令、從 Claude Code 操作資源，以及使用 CLI 憑證驗證 curl 呼叫。

本頁涵蓋以 ant CLI 為基礎的任務導向工作流程。關於底層的旗標與輸出選項，請參閱使用 CLI。

對 API 資源進行版本控制

您可以使用 CLI 將 API 資源（例如 skills、agents、environments 或 deployments）以 YAML 檔案的形式在您的儲存庫中進行版本控制，並使其與 Claude API 保持同步。

關於這些資源的更多資訊，請參閱 Managed Agents。

定義您的 agent

將 agent 定義寫入 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

建立 agent

ant beta:agents create < summarizer.agent.yaml

Output

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

記下回應中的 id。您將在後續步驟中將其傳遞給 session create 命令。

將 summarizer.agent.yaml 簽入您的儲存庫，並在您的 CI 管線中使其與 API 保持同步。update 命令需要以旗標提供 agent ID 和目前版本：

CLI

ant beta:agents update --agent-id agent_011CYm1BLqPXpQRk5khsSXrs --version 1 < summarizer.agent.yaml

定義 environment
session 會在一個 environment 中執行，它定義了執行所在的沙箱。將 environment 定義寫入 summarizer.environment.yaml：
summarizer.environment.yaml
name: summarizer-env config: type: cloud networking: type: unrestricted
建立 environment
ant beta:environments create < summarizer.environment.yaml
Output
{ "id": "env_01595EKxaaTTGwwY3kyXdtbs", "name": "summarizer-env" /* ... */ }
記下回應中的 id。您將在後續步驟中將其傳遞給 session create 命令。
將 summarizer.environment.yaml 簽入您的儲存庫，並在您的 CI 管線中使其與 API 保持同步。update 命令需要以旗標提供 environment ID：
CLI
ant beta:environments update --environment-id env_01595EKxaaTTGwwY3kyXdtbs < summarizer.environment.yaml

啟動 session

將先前輸出中的 agent id 和 environment id 貼入 session create 命令：

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

Output

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

傳送使用者訊息

將先前輸出中的 session 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.

若要在 session 執行時即時觀看，請使用 ant beta:sessions:events stream --session-id session_01JZCh78XvmxJjiXVy3oSi7K。事件會在抵達時寫入 stdout。

指令碼撰寫模式

CLI 的設計可與標準 shell 工具組合使用。

將 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 資源。例如：

「列出我最近的 agent sessions，並總結哪些發生了錯誤。」
「將 ./reports 中的每個 PDF 上傳到 Files API，並印出產生的 ID。」
「取得 session session_01... 的事件，並告訴我 agent 在哪裡卡住了。」

Claude Code 會透過 shell 呼叫 ant，解析結構化輸出，並對結果進行推理（無需自訂整合程式碼）。

使用 CLI 憑證驗證 curl 請求

使用 curl 或其他 HTTP 用戶端呼叫 API 的指令碼，可以使用由 ant auth login 儲存的憑證，而非靜態 API 金鑰。OAuth 存取權杖會以 bearer token 的形式放在 Authorization 標頭中；x-api-key 標頭僅用於靜態 API 金鑰。

ant auth print-credentials --access-token 會印出目前使用中設定檔的存取權杖，如果權杖已過期或即將過期，會先進行重新整理：

cURL

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"}]
  }'

透過 CLI 登入工作時，請保持 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 未設定。這兩個變數中的任一個都會在 ant 命令中優先於登入憑證（請參閱憑證優先順序），並可能在無提示的情況下將命令導向不同的組織或工作區。

執行 ant auth status 以確認您登入的組織和工作區；當環境變數覆寫您的登入時，它會發出警告。

Was this page helpful?

CLI、SDK 與函式庫ant CLI

CLI 指令碼與自動化

將 API 資源以 YAML 進行版本控制、在指令碼中串接 ant CLI 命令、從 Claude Code 操作資源，以及使用 CLI 憑證驗證 curl 呼叫。

本頁涵蓋以 ant CLI 為基礎的任務導向工作流程。關於底層的旗標與輸出選項，請參閱使用 CLI。

對 API 資源進行版本控制

您可以使用 CLI 將 API 資源（例如 skills、agents、environments 或 deployments）以 YAML 檔案的形式在您的儲存庫中進行版本控制，並使其與 Claude API 保持同步。

關於這些資源的更多資訊，請參閱 Managed Agents。

定義您的 agent

將 agent 定義寫入 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

建立 agent

ant beta:agents create < summarizer.agent.yaml

Output

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

記下回應中的 id。您將在後續步驟中將其傳遞給 session create 命令。

將 summarizer.agent.yaml 簽入您的儲存庫，並在您的 CI 管線中使其與 API 保持同步。update 命令需要以旗標提供 agent ID 和目前版本：

CLI

ant beta:agents update --agent-id agent_011CYm1BLqPXpQRk5khsSXrs --version 1 < summarizer.agent.yaml

定義 environment
session 會在一個 environment 中執行，它定義了執行所在的沙箱。將 environment 定義寫入 summarizer.environment.yaml：
summarizer.environment.yaml
name: summarizer-env config: type: cloud networking: type: unrestricted
建立 environment
ant beta:environments create < summarizer.environment.yaml
Output
{ "id": "env_01595EKxaaTTGwwY3kyXdtbs", "name": "summarizer-env" /* ... */ }
記下回應中的 id。您將在後續步驟中將其傳遞給 session create 命令。
將 summarizer.environment.yaml 簽入您的儲存庫，並在您的 CI 管線中使其與 API 保持同步。update 命令需要以旗標提供 environment ID：
CLI
ant beta:environments update --environment-id env_01595EKxaaTTGwwY3kyXdtbs < summarizer.environment.yaml

啟動 session

將先前輸出中的 agent id 和 environment id 貼入 session create 命令：

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

Output

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

傳送使用者訊息

將先前輸出中的 session 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.

若要在 session 執行時即時觀看，請使用 ant beta:sessions:events stream --session-id session_01JZCh78XvmxJjiXVy3oSi7K。事件會在抵達時寫入 stdout。

指令碼撰寫模式

CLI 的設計可與標準 shell 工具組合使用。

將 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

Claude Code 可以直接使用 ant CLI。在安裝並驗證 CLI 之後，您可以要求 Claude Code 直接操作您的 API 資源。例如：

「列出我最近的 agent sessions，並總結哪些發生了錯誤。」
「將 ./reports 中的每個 PDF 上傳到 Files API，並印出產生的 ID。」
「取得 session session_01... 的事件，並告訴我 agent 在哪裡卡住了。」

Claude Code 會透過 shell 呼叫 ant，解析結構化輸出，並對結果進行推理（無需自訂整合程式碼）。

使用 CLI 憑證驗證 curl 請求

ant auth print-credentials --access-token 會印出目前使用中設定檔的存取權杖，如果權杖已過期或即將過期，會先進行重新整理：

cURL

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 以確認您登入的組織和工作區；當環境變數覆寫您的登入時，它會發出警告。

Was this page helpful?

對 API 資源進行版本控制

指令碼撰寫模式

將 list 輸出串接到第二個命令

檢查錯誤

從 Claude Code 使用 CLI

使用 CLI 憑證驗證 curl 請求

對 API 資源進行版本控制

指令碼撰寫模式

將 list 輸出串接到第二個命令

檢查錯誤

從 Claude Code 使用 CLI

使用 CLI 憑證驗證 curl 請求

對 API 資源進行版本控制

指令碼撰寫模式

將 list 輸出串接到第二個命令

檢查錯誤

從 Claude Code 使用 CLI

使用 CLI 憑證驗證 curl 請求

對 API 資源進行版本控制

指令碼撰寫模式

將 list 輸出串接到第二個命令

檢查錯誤

從 Claude Code 使用 CLI

使用 CLI 憑證驗證 curl 請求