开始使用 Claude Managed Agents

本指南将引导您完成创建智能体、设置环境、启动会话以及流式传输智能体响应的全过程。

核心概念

Concept	Description
Agent	The model, system prompt, tools, MCP servers, and skills
Environment	A configured container template (packages, network access)
Session	A running agent instance within an environment, performing a specific task and generating outputs
Events	Messages exchanged between your application and the agent (user turns, tool results, status updates)

前提条件

一个 Anthropic Console 账户
一个 API 密钥

安装 CLI

检查安装情况：

ant --version

安装 SDK

将您的 API 密钥设置为环境变量：

export ANTHROPIC_API_KEY="your-api-key-here"

创建您的第一个会话

所有 Managed Agents API 请求都需要 managed-agents-2026-04-01 beta 请求头。SDK 会自动设置该 beta 请求头。

发生了什么

当您发送用户事件时，Claude Managed Agents 会：

配置容器： 您的环境配置决定了容器的构建方式。
运行智能体循环： Claude 根据您的消息决定使用哪些工具
执行工具： 文件写入、bash 命令和其他工具调用在容器内运行
流式传输事件： 您会在智能体工作时实时收到更新
进入空闲状态： 当智能体没有更多任务时，会发出 session.status_idle 事件

后续步骤

定义您的智能体

创建可复用的、版本化的智能体配置

创建智能体

创建一个定义模型、系统提示词和可用工具的智能体。

set -euo pipefail

agent=$(
  curl -sS --fail-with-body https://api.anthropic.com/v1/agents \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d @- <<'EOF'
{
  "name": "Coding Assistant",
  "model": "claude-sonnet-4-6",
  "system": "You are a helpful coding assistant. Write clean, well-documented code.",
  "tools": [
    {"type": "agent_toolset_20260401"}
  ]
}
EOF
)

AGENT_ID=$(jq -er '.id' <<<"$agent")
AGENT_VERSION=$(jq -er '.version' <<<"$agent")

echo "Agent ID: $AGENT_ID, version: $AGENT_VERSION"

agent_toolset_20260401 工具类型启用了完整的预构建智能体工具集（bash、文件操作、网络搜索等）。请参阅工具以获取完整列表和每个工具的配置选项。

保存返回的 agent.id。您将在创建的每个会话中引用它。

创建环境

环境定义了智能体运行所在的容器。

environment=$(
  curl -sS --fail-with-body https://api.anthropic.com/v1/environments \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d @- <<'EOF'
{
  "name": "quickstart-env",
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"}
  }
}
EOF
)

ENVIRONMENT_ID=$(jq -er '.id' <<<"$environment")

echo "Environment ID: $ENVIRONMENT_ID"

保存返回的 environment.id。您将在创建的每个会话中引用它。

启动会话

创建一个引用您的智能体和环境的会话。

session=$(
  curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "title": "Quickstart session"
}
EOF
)

SESSION_ID=$(jq -er '.id' <<<"$session")

echo "Session ID: $SESSION_ID"

发送消息并流式传输响应

打开流，发送用户事件，然后在事件到达时处理它们：

# Send the user message first; the API buffers events until the stream attaches
curl -sS --fail-with-body \
  "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- >/dev/null <<'EOF'
{
  "events": [
    {
      "type": "user.message",
      "content": [
        {
          "type": "text",
          "text": "Create a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt"
        }
      ]
    }
  ]
}
EOF

# Open the SSE stream and process events as they arrive
while IFS= read -r line; do
  [[ $line == data:* ]] || continue
  json=${line#data: }
  case $(jq -r '.type' <<<"$json") in
    agent.message)
      jq -j '.content[] | select(.type == "text") | .text' <<<"$json"
      ;;
    agent.tool_use)
      printf '\n[Using tool: %s]\n' "$(jq -r '.name' <<<"$json")"
      ;;
    session.status_idle)
      printf '\n\nAgent finished.\n'
      break
      ;;
  esac
done < <(
  curl -sS -N --fail-with-body \
    "https://api.anthropic.com/v1/sessions/$SESSION_ID/stream" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "Accept: text/event-stream"
)

智能体将编写一个 Python 脚本，在容器中执行它，并验证输出文件是否已创建。您的输出将类似于以下内容：

I'll create a Python script that generates the first 20 Fibonacci numbers and saves them to a file.
[Using tool: write]
[Using tool: bash]
The script ran successfully. Let me verify the output file.
[Using tool: bash]
fibonacci.txt contains the first 20 Fibonacci numbers (0 through 4181).

Agent finished.