CLI、SDK 与库ant CLI

CLI 脚本编写与自动化

将 API 资源以 YAML 形式进行版本控制、在脚本中串联 ant CLI 命令、从 Claude Code 操作资源，以及使用 CLI 凭据对 curl 调用进行身份验证。

本页介绍基于 ant CLI 构建的面向任务的工作流。有关底层标志和输出选项，请参阅使用 CLI。

对 API 资源进行版本控制

您可以使用 CLI 将技能、代理、环境或部署等 API 资源作为 YAML 文件在您的仓库中进行版本控制，并使其与 Claude API 保持同步。

有关这些资源的更多信息，请参阅托管代理。

定义您的代理

将代理定义写入 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

创建代理

ant beta:agents create < summarizer.agent.yaml

Output

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

记下响应中的 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。在安装并完成身份验证后，您可以让 Claude Code 直接操作您的 API 资源。例如：

"列出我最近的代理会话，并总结哪些出错了。"
"将 ./reports 中的每个 PDF 上传到 Files API 并打印生成的 ID。"
"拉取会话 session_01... 的事件，并告诉我代理在哪里卡住了。"

Claude Code 会通过 shell 调用 ant，解析结构化输出，并对结果进行推理（无需自定义集成代码）。

使用 CLI 凭据对 curl 请求进行身份验证

使用 curl 或其他 HTTP 客户端调用 API 的脚本可以使用 ant auth login 存储的凭据，而不是静态 API 密钥。OAuth 访问令牌作为 bearer 令牌放在 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 资源作为 YAML 文件在您的仓库中进行版本控制，并使其与 Claude API 保持同步。

有关这些资源的更多信息，请参阅托管代理。

定义您的代理

将代理定义写入 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

创建代理

ant beta:agents create < summarizer.agent.yaml

Output

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

记下响应中的 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 工具组合使用。

将列表输出串联到第二个命令

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。在安装并完成身份验证后，您可以让 Claude Code 直接操作您的 API 资源。例如：

"列出我最近的代理会话，并总结哪些出错了。"
"将 ./reports 中的每个 PDF 上传到 Files API 并打印生成的 ID。"
"拉取会话 session_01... 的事件，并告诉我代理在哪里卡住了。"

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 资源进行版本控制

脚本编写模式

将列表输出串联到第二个命令

检查错误

从 Claude Code 使用 CLI

使用 CLI 凭据对 curl 请求进行身份验证

对 API 资源进行版本控制

脚本编写模式

将列表输出串联到第二个命令

检查错误

从 Claude Code 使用 CLI

使用 CLI 凭据对 curl 请求进行身份验证

对 API 资源进行版本控制

脚本编写模式

将列表输出串联到第二个命令

检查错误

从 Claude Code 使用 CLI

使用 CLI 凭据对 curl 请求进行身份验证

对 API 资源进行版本控制

脚本编写模式

将列表输出串联到第二个命令

检查错误

从 Claude Code 使用 CLI

使用 CLI 凭据对 curl 请求进行身份验证