Claude Managed Agents 快速入门笔记

一、核心概念体系

概念	定义
Agent（智能体）	由模型、系统提示词、工具、MCP 服务器和技能组成的配置实体
Environment（环境）	预配置的容器模板（包含软件包、网络访问等运行时设置）
Session（会话）	在环境中运行的智能体实例，执行特定任务并生成输出
Events（事件）	应用与智能体之间交换的消息（用户输入、工具结果、状态更新）

二、前置条件

Anthropic Console 账户
API 密钥（在 /settings/keys 获取）

三、CLI 工具安装

macOS (Homebrew)：

bash 复制代码

brew install anthropics/tap/ant
xattr -d com.apple.quarantine "$(brew --prefix)/bin/ant"  # 解除隔离

验证安装：

bash 复制代码

ant --version

四、SDK 安装

bash 复制代码

pip install anthropic

环境变量配置：

bash 复制代码

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

五、关键 API 版本要求

所有 Managed Agents API 请求必须包含 managed-agents-2026-04-01 beta 头部。 SDK 会自动设置此头部。

六、四步创建首个会话

步骤 1：创建 Agent

bash 复制代码

ant beta:agents create \
  --name "Coding Assistant" \
  --model '{id: claude-sonnet-4-6}' \
  --system "You are a helpful coding assistant. Write clean, well-documented code." \
  --tool '{type: agent_toolset_20260401}'

关键参数说明：

agent_toolset_20260401：启用完整的预构建工具集（bash、文件操作、网络搜索等）
需保存返回的 agent.id

步骤 2：创建环境

bash 复制代码

ant beta:environments create \
  --name "quickstart-env" \
  --config '{type: cloud, networking: {type: unrestricted}}'

需保存返回的 environment.id
networking: unrestricted 表示无限制网络访问

步骤 3：启动会话（cURL 示例）

bash 复制代码

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 '{
    "agent": "$AGENT_ID",
    "environment_id": "$ENVIRONMENT_ID",
    "title": "Quickstart session"
  }'

步骤 4：发送消息并流式响应

先发送用户消息：

bash 复制代码

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

再打开 SSE 流接收事件：

bash 复制代码

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"

七、事件处理逻辑（SSE 流解析）

事件类型	处理方式
`agent.message`	提取 `.content[]` 中 `type: "text"` 的文本片段
`agent.tool_use`	显示 `[Using tool: {name}]`
`session.status_idle`	智能体完成，终止循环

八、执行流程解析

复制代码

用户发送消息
    ↓
[1] 容器预置（按环境配置构建）
    ↓
[2] 智能体循环运行（Claude 决策使用哪些工具）
    ↓
[3] 工具执行（文件写入、bash 命令等在容器内运行）
    ↓
[4] 事件流推送（实时更新执行状态）
    ↓
[5] 空闲状态（session.status_idle → 任务完成）

九、关键设计要点

分离式架构：Agent（配置）与环境（运行时）解耦，支持复用
流式优先：SSE 实时推送，适合长时运行的自动化任务
容器化执行：所有工具调用在隔离环境中运行，保障安全
版本化工具集 ：agent_toolset_20260401 显式声明工具版本

十、后续学习路径

主题	内容
Define your agent	创建可复用、版本化的智能体配置
Configure environments	自定义网络和容器设置
Agent tools	为智能体启用特定工具
Events and streaming	处理事件并在执行中引导智能体

十一、与标准 Claude API 的核心差异

维度	标准 Messages API	Managed Agents API
执行模型	单次请求-响应	长时运行的自主循环
工具执行	客户端执行（需返回结果）	服务端容器内自动执行
状态管理	无状态（需自行维护上下文）	有状态会话（session 持久化）
适用场景	对话、单次任务	复杂多步自动化、代码生成与执行
API 版本	`2023-06-01`	需额外 `managed-agents-2026-04-01` beta