CLI 脚本编写与自动化

对 API 资源进行版本控制

您可以使用 CLI 将 API 资源（如技能、智能体、环境或部署）以 YAML 文件的形式在代码仓库中进行版本控制，并使其与 Claude API 保持同步。

有关这些资源的更多信息，请参阅托管智能体。

定义您的智能体

将智能体定义写入 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 会覆盖列表命令在终端中默认打开的交互式浏览器：

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 的设计旨在与标准 shell 工具组合使用。

将列表输出链接到第二个命令

在列表端点上使用 --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 会通过 shell 调用 ant，解析结构化输出，并对结果进行推理（无需自定义集成代码）。