Claude Managed Agents 快速入门笔记

一、核心概念体系

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

---

二、前置条件

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

---

三、CLI 工具安装

macOS (Homebrew)：

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

验证安装：

ant --version

---

四、SDK 安装

pip install anthropic

环境变量配置：

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

---

五、关键 API 版本要求

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

---

六、四步创建首个会话

步骤 1：创建 Agent

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：创建环境

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

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

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

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：发送消息并流式响应

先发送用户消息：

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 流接收事件：

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 → 任务完成）

---

九、关键设计要点

1. 分离式架构：Agent（配置）与环境（运行时）解耦，支持复用
2. 流式优先：SSE 实时推送，适合长时运行的自动化任务
3. 容器化执行：所有工具调用在隔离环境中运行，保障安全
4. 版本化工具集：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