Claude Platform Docs

CLI 腳本與自動化

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

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

對 API 資源進行版本控制

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

  1. 定義您的 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

  2. 建立 agent

    ant beta:agents create < summarizer.agent.yaml
    Output
    {
  "id": "agent_011CYm1BLqPXpQRk5khsSXrs",
  "version": 1,
  "name": "Summarizer",
  "model": "claude-opus-5"
  /* ... */
}

    請記下回應中的 id。您將在後續步驟中將其傳遞給 session 建立指令。

  3. 定義 environment

    Session 在 environment（環境）中執行，environment 定義了其執行所在的沙箱。將 environment 定義寫入 summarizer.environment.yaml：

    summarizer.environment.yaml
    name: summarizer-env
config:
  type: cloud
  networking:
    type: unrestricted

  4. 建立 environment

    ant beta:environments create < summarizer.environment.yaml
    Output
    {
  "id": "env_01595EKxaaTTGwwY3kyXdtbs",
  "name": "summarizer-env"
  /* ... */
}

    請記下回應中的 id。您將在後續步驟中將其傳遞給 session 建立指令。

  5. 啟動 session

    將先前輸出中的 agent id 與 environment id 貼入 session 建立指令：

    ant beta:sessions create \
  --agent agent_011CYm1BLqPXpQRk5khsSXrs \
  --environment-id env_01595EKxaaTTGwwY3kyXdtbs \
  --title "Summarization task"
    Output
    {
  "id": "session_01JZCh78XvmxJjiXVy3oSi7K",
  "status": "running"
  /* ... */
}

  6. 傳送使用者訊息

    將先前輸出中的 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."}]}'

  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 的設計可與標準 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 會呼叫 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"}]
  }'

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

Was this page helpful?