【Claude基础】09.多代理协作：Agent Teams与编排模式
-
1. Managed Agents vs Claude Code 子代理
-
1.1 定位区分
-
1.2 选择标准
-
1.3 决策矩阵
-
2. 四要素架构模型
-
2.1 Agent — 定义"谁来干活"
-
2.2 Environment — 定义"在哪干活"
-
2.3 Session — 定义"一次干活过程"
-
2.4 Events — 定义"怎么交流"
-
3. 完整工作流程
-
3.1 五步流程
-
3.2 Python SDK 代码示例
-
3.3 中途引导
-
4. 内置工具
-
4.1 Bash — 容器内 Shell
-
4.2 文件操作
-
4.3 Web Search / Web Fetch
-
4.4 MCP 服务器接入
-
5. 定价模型详解
-
5.1 Token 费用
-
5.2 Session 运行时
-
5.3 成本计算示例
-
5.4 与自建基础设施的成本对比
-
6. 适用场景分析
-
6.1 大规模代码迁移
-
6.2 自动化测试生成
-
6.3 数据处理流水线
-
6.4 持续集成中的代码审查
-
7. Beta 注意事项
-
7.1 Beta Header
-
7.2 行为变更
-
7.3 速率限制
-
7.4 研究预览功能
-
小结
1. Managed Agents vs Claude Code 子代理
上一篇讲的子代理，本质上是在你本地机器上跑的。父代理派出子代理，子代理在你的文件系统里读写文件、在你的终端里执行命令——一切都发生在你的笔记本或工作站上。
Managed Agents（托管智能体）是完全不同的东西。它运行在 Anthropic 的云端基础设施上，有自己的容器化环境、独立的文件系统、独立的生命周期。你的笔记本关机了，它还在跑。
1.1 定位区分
Claude Code 子代理是本地 CLI 工具的延伸。它依赖你的机器运行，共享你的文件系统，受限于你的网络和计算资源。适合的场景是：你坐在电脑前，需要把一个复杂任务拆分成几个并行子任务，几分钟到几十分钟内完成。
Managed Agents是云端托管平台。它跑在 Anthropic 管理的容器里，有独立的计算资源、独立的网络环境、持久化的文件系统。适合的场景是：你不想盯着屏幕等，任务可能跑几小时，需要稳定的运行环境和可编程的 API 接口。
两者不是替代关系，而是互补关系。就像你不会用 SSH 远程服务器来做本地代码补全，也不会用本地 IDE 来跑 CI/CD 流水线一样。
1.2 选择标准
判断该用哪个，看三个维度：
任务时长。几分钟的事情，用子代理。几十分钟到几小时的长时任务，用 Managed Agents。本地跑长时任务的问题是：你的机器不能关，网络不能断，进程不能被意外杀掉。
是否需要云基础设施。如果任务需要特定的运行环境（比如 GPU、特定版本的 Python、预装的依赖包），或者需要访问特定的网络资源（内网服务、数据库），Managed Agents 的容器化环境比你本地更可控。
是否需要有状态。Managed Agents 的 Session 是有状态的——文件系统在 session 存活期间持久化，对话历史自动保留。你可以今天创建一个 session，明天继续在同一个 session 里工作，所有的文件和上下文都还在。子代理做不到这一点，它完成任务就没了。
1.3 决策矩阵
| 维度 | Messages API | Claude Code 子代理 | Managed Agents |
|---|---|---|---|
| 运行位置 | Anthropic 云端（无状态） | 你的本地机器 | Anthropic 云端容器 |
| 有无工具 | 需要自己实现工具 | 内置完整工具集 | 内置完整工具集 |
| 状态管理 | 无状态，每次请求独立 | 会话内有状态，会话结束丢失 | 持久化状态，跨请求保持 |
| 文件系统 | 无 | 共享本地文件系统 | 独立容器文件系统 |
| 任务时长 | 单次请求级（秒到分钟） | 分钟级 | 分钟到小时级 |
| 自动化集成 | REST API | CLI / SDK | REST API / SDK |
| 适合场景 | 简单问答、文本生成 | 本地开发辅助 | 长时任务、CI/CD、后台处理 |
| 代码执行 | 不能 | 可以（本地） | 可以（容器内） |
一句话概括：Messages API 是"问一句答一句"，子代理是"本地帮手"，Managed Agents 是"云端长工"。
2. 四要素架构模型
Managed Agents 的架构由四个核心概念组成：Agent、Environment、Session、Events。理解这四个概念，就理解了整个系统的运作方式。
2.1 Agent — 定义"谁来干活"
Agent 定义了智能体的身份和能力。它包含以下要素：
-
模型：使用哪个 Claude 模型（claude-sonnet-4-20250514、claude-opus-4-20250514 等）
-
系统提示：告诉模型它是谁、该怎么做事
-
工具：赋予模型哪些能力（bash、文件操作、web 搜索等）
-
MCP 服务器：要连接哪些外部服务
-
技能：可复用的指令集
Agent 的关键特性是创建一次，跨 Session 复用。你定义好一个"代码审查 Agent"，它就一直存在，可以在不同的 Session 中反复使用。Agent 本身是无状态的配置模板——它描述的是"这个智能体长什么样"，而不是"这个智能体正在干什么"。
Agent 支持版本管理。你可以更新 Agent 的配置（比如换个更好的系统提示），新的 Session 会自动使用最新版本，已有的 Session 不受影响。
2.2 Environment — 定义"在哪干活"
Environment 是容器模板，定义了 Agent 的运行环境：
-
预装软件包：Python、Node.js、Go 等运行时，pip/npm/go 等包管理器
-
网络访问规则：容器能不能访问互联网，能访问哪些域名
-
文件挂载：需要预载到容器里的文件或代码仓库
你可以把 Environment 理解为一个 Dockerfile 的抽象。Anthropic 帮你管理容器的创建和销毁，你只需要告诉它"我需要一个装了 Python 3.12 和 Node.js 20 的环境"。
Environment 也是可复用的。同一个 Environment 可以被多个 Agent 使用，同一个 Agent 也可以在不同的 Environment 中运行。
2.3 Session — 定义"一次干活过程"
Session 是 Agent 在 Environment 中的一次运行实例。它有明确的生命周期：
created → running → idle → terminated
-
created：Session 已创建，容器正在启动
-
running：Agent 正在执行任务（处理消息、调用工具）
-
idle：Agent 完成了当前任务，等待新的指令。容器还活着，文件系统保持不变
-
terminated：Session 已结束，容器被回收
Session 有两个重要的持久化特性：
文件系统持久化。Session 存活期间，Agent 创建的所有文件都保留在容器里。你在第一条消息里让它克隆一个仓库，第十条消息里让它修改某个文件——仓库还在那里，不需要重新克隆。
对话历史持久化。Session 自动记录所有的消息交换。Agent 在第五轮对话中可以引用第一轮的讨论内容，不会"失忆"。
2.4 Events — 定义"怎么交流"
Events 是你和 Agent 之间的消息交换机制。分两种：
用户事件：你发送给 Agent 的消息。可以是文本指令、代码片段、文件内容——任何你想告诉 Agent 的信息。
代理事件：Agent 返回给你的消息。包括文本回复、工具调用过程、工具执行结果等。
Events 支持 SSE（Server-Sent Events）流式接收。你不需要等 Agent 把整个任务做完才能看到结果——它做一步你就能看到一步，实时跟踪进度。
四个概念的关系可以这样理解：Agent 是员工的简历（技能和职责），Environment 是办公室（硬件和软件环境），Session 是一次上班（从打卡到下班），Events 是工作中的对话（布置任务和汇报结果）。
3. 完整工作流程
3.1 五步流程
整个使用流程分五步：
-
定义 Agent：指定模型、系统提示、工具集
-
配置 Environment：指定容器模板、预装包、网络规则
-
启动 Session：把 Agent 和 Environment 绑定，创建运行实例
-
发送事件，流式接收：给 Agent 布置任务，实时接收结果
-
中途引导或中断：Agent 在执行过程中，你可以发送新的指令来调整方向，或者直接终止 Session
3.2 Python SDK 代码示例
下面是一个完整的工作流代码，从创建 Agent 到接收结果：
import anthropic
client = anthropic.Anthropic()
# 第一步：创建 Agent
agent = client.agents.create(
model="claude-sonnet-4-20250514",
name="code-reviewer",
instructions="""你是一个严格的代码审查员。
对提交的代码进行以下检查：
1. 代码风格是否一致
2. 是否有潜在的性能问题
3. 错误处理是否完善
4. 是否有安全隐患
给出具体的行号和修改建议。""",
tools=[
{"type": "bash"},
{"type": "file_read"},
{"type": "file_write"},
{"type": "file_edit"},
{"type": "glob"},
{"type": "grep"},
{"type": "web_search"},
],
)
print(f"Agent 已创建: {agent.id}")
# 第二步：创建 Environment
environment = client.environments.create(
name="python-dev",
setup_commands=[
"pip install pytest black flake8",
"git config --global user.name 'Code Reviewer'",
],
)
print(f"Environment 已创建: {environment.id}")
# 第三步：启动 Session
session = client.sessions.create(
agent_id=agent.id,
environment_id=environment.id,
)
print(f"Session 已启动: {session.id}")
# 第四步：发送消息并流式接收
with client.sessions.turn.create_stream(
session_id=session.id,
messages=[
{
"role": "user",
"content": "克隆 https://github.com/example/project.git，"
"对 src/ 目录下所有 Python 文件做代码审查。",
}
],
) as stream:
for event in stream:
if event.type == "message_start":
print("Agent 开始回复...")
elif event.type == "content_block_delta":
print(event.delta.text, end="", flush=True)
elif event.type == "tool_use":
print(f"\n[调用工具: {event.name}]")
elif event.type == "message_stop":
print("\nAgent 回复完毕。")
如果你不需要流式接收，也可以用同步方式等待结果：
# 同步方式——等待完成后一次性获取结果
turn = client.sessions.turn.create(
session_id=session.id,
messages=[
{
"role": "user",
"content": "运行 pytest，把测试结果汇总给我。",
}
],
)
# turn.response 包含 Agent 的完整回复
for block in turn.response:
if block.type == "text":
print(block.text)
3.3 中途引导
Session 进入 idle 状态后，你可以继续发消息。Agent 会基于之前的上下文继续工作：
# 第一轮：审查代码
# ...（如上）
# 第二轮：基于审查结果修复
with client.sessions.turn.create_stream(
session_id=session.id,
messages=[
{
"role": "user",
"content": "刚才审查发现的那3个高危问题，帮我修复。修完后跑一遍测试确认没有回归。",
}
],
) as stream:
for event in stream:
# 处理事件...
pass
Agent 记得上一轮审查发现了什么问题、文件在哪里、项目结构是什么样的——不需要你重复说明。
4. 内置工具
Managed Agents 的容器内预装了一套工具，覆盖了绝大多数开发场景。
4.1 Bash — 容器内 Shell
{"type": "bash"}
给 Agent 一个完整的 shell 环境。它可以执行任意命令：克隆仓库、安装依赖、运行测试、编译代码、执行脚本。跟你在终端里能做的事情一样。
容器预装了常用工具链（git、curl、wget 等），加上 Environment 配置阶段安装的语言运行时和包，基本上拿到手就能用。
Bash 工具有超时机制，单条命令不会无限期运行。如果你的任务需要跑很久的编译或测试，Agent 会自动分批处理。
4.2 文件操作
容器内提供完整的文件操作工具集：
-
file_read：读取文件内容，支持指定行范围
-
file_write：创建或覆盖文件
-
file_edit：精确的文本替换（而不是重写整个文件）
-
glob：按模式匹配查找文件（
**/*.py、src/**/*.ts） -
grep：在文件内容中搜索正则表达式
这套工具和 Claude Code 本地版的工具集高度一致。如果你已经习惯了 Claude Code 的文件操作方式，Managed Agents 的体验几乎一样。
4.3 Web Search / Web Fetch
{"type": "web_search"}
{"type": "web_fetch"}
web_search 让 Agent 可以搜索互联网。当它遇到不确定的 API 用法、需要查最新的文档、或者想看看某个错误信息的解决方案时，能直接去搜。
web_fetch 让 Agent 可以抓取指定 URL 的内容。下载文件、读取 API 文档、获取配置模板——都靠它。
这两个工具让 Agent 不再是一个封闭系统。它可以像一个真实的开发者一样，遇到问题上网查。
4.4 MCP 服务器接入
Managed Agents 支持连接 MCP（Model Context Protocol）服务器，扩展 Agent 的能力边界。
agent = client.agents.create(
model="claude-sonnet-4-20250514",
name="db-analyst",
instructions="你是一个数据库分析专家。",
tools=[
{"type": "bash"},
{"type": "file_read"},
],
mcp_servers={
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"POSTGRES_CONNECTION_STRING": "postgresql://..."
},
}
},
)
通过 MCP，Agent 可以直接操作数据库、调用第三方 API、访问内部工具——任何有 MCP 适配器的服务都能接入。这极大地扩展了 Managed Agents 的适用范围。
5. 定价模型详解
Managed Agents 的费用由两部分组成：Token 费用 + Session 运行时费用。
5.1 Token 费用
跟 Messages API 完全一样的费率，按模型定价：
| 模型 | 输入 Token | 输出 Token |
|---|---|---|
| Claude Sonnet 4 | $3 / 百万 | $15 / 百万 |
| Claude Opus 4 | $15 / 百万 | $75 / 百万 |
如果触发了 Prompt Caching，缓存命中的 token 按照对应模型的缓存读取价格计费（通常是输入价格的 10%），首次写入缓存的 token 按写入价格计费（通常是输入价格的 125%）。
5.2 Session 运行时
$0.08 / 小时，按秒计费。
只有 running 状态才计费。Session 处于 idle（等待你的下一条指令）或 terminated（已结束）状态时，不收运行时费用。
换句话说，你只为 Agent 实际干活的时间付费。Agent 在等你想好下一步该做什么的时候，不烧钱。
5.3 成本计算示例
场景一：一小时编码会话，使用 Opus 4
假设一个小时的编码 session 中，Agent 处理了 50K 输入 token 和 15K 输出 token：
输入 Token 费用: 50,000 / 1,000,000 × $15 = $0.75
输出 Token 费用: 15,000 / 1,000,000 × $75 = $1.125
运行时费用: 1 小时 × $0.08 = $0.08
──────────────────────────────────────
总计: $1.955
运行时费用占比很小（约 4%），大头在 token 上。
场景二：同样的任务，使用 Sonnet 4
输入 Token 费用: 50,000 / 1,000,000 × $3 = $0.15
输出 Token 费用: 15,000 / 1,000,000 × $15 = $0.225
运行时费用: 1 小时 × $0.08 = $0.08
──────────────────────────────────────
总计: $0.455
Sonnet 的性价比优势在这里体现得很明显。
场景三：带 Prompt Caching 的 Sonnet 4 会话
假设 50K 输入 token 中，有 40K 命中了缓存：
缓存命中 Token: 40,000 / 1,000,000 × $0.30 = $0.012
非缓存输入 Token: 10,000 / 1,000,000 × $3 = $0.03
输出 Token 费用: 15,000 / 1,000,000 × $15 = $0.225
运行时费用: 1 小时 × $0.08 = $0.08
──────────────────────────────────────
总计: $0.347
缓存命中率高的时候，成本下降非常显著。
5.4 与自建基础设施的成本对比
如果你自己搭建类似的基础设施——运行容器、管理生命周期、实现工具集、处理网络和存储——需要：
-
容器编排（Kubernetes/ECS）的运维成本
-
持久存储的费用
-
网络带宽费用
-
工具链的开发和维护成本
-
安全隔离的实现成本
对于大多数团队来说，$0.08/小时的运行时费用远低于自建方案的综合成本。当然，如果你的规模大到每月跑几万个 Session，自建可能开始有成本优势——但那时候你可能也有专门的基础设施团队了。
6. 适用场景分析
哪些任务适合交给 Managed Agents？核心判断标准是：任务耗时长、可以后台运行、需要稳定的执行环境。
6.1 大规模代码迁移
把一个 50 万行的 Java 项目从 Java 8 迁移到 Java 17——这种任务手工做能做一个月。交给 Managed Agents：
-
创建一个 Agent，系统提示里写清楚迁移规则（deprecated API 的替代方案、新语法特性的使用标准）
-
配置一个装了 JDK 17 和 Maven 的 Environment
-
启动 Session，让 Agent 克隆仓库，按模块逐个迁移
-
Agent 每迁完一个模块就跑一遍编译和测试，确认没有破坏
-
你隔几个小时来看看进度，有问题的地方给点指导
整个过程可能跑几个小时。如果是本地子代理，你的电脑得开着不能动。用 Managed Agents，你可以关机去吃饭，回来看结果。
6.2 自动化测试生成
现有项目测试覆盖率不够？让 Agent 去补：
-
Agent 先分析项目结构，找出哪些模块缺少测试
-
读懂每个模块的业务逻辑
-
生成单元测试、集成测试
-
运行测试确认全部通过
-
生成覆盖率报告
这类任务的特点是：高度重复（给 100 个模块写测试，套路是一样的），但每个模块的具体逻辑不同，需要 Agent 真正理解代码才能写出有意义的测试。Managed Agents 的持久化 Session 在这里很有用——Agent 在前面几个模块中积累的项目理解，后面的模块也能受益。
6.3 数据处理流水线
ETL 任务、日志分析、数据清洗——这些任务的共同特点是"给一堆数据，按规则处理，输出结果"：
# 创建数据处理 Agent
agent = client.agents.create(
model="claude-sonnet-4-20250514",
name="data-pipeline",
instructions="""你是一个数据处理专家。
读取 /data/raw 目录下的 CSV 文件，执行以下处理：
1. 清洗：去除空行、修复编码问题、标准化日期格式
2. 转换：按照 schema.json 中定义的规则转换字段
3. 验证：检查必填字段、数据类型、值域范围
4. 输出：将处理后的数据写入 /data/processed/
5. 报告：生成处理报告，包括原始记录数、有效记录数、
丢弃记录数及原因""",
tools=[
{"type": "bash"},
{"type": "file_read"},
{"type": "file_write"},
],
)
Agent 可以写 Python 脚本处理数据，也可以直接用 bash 工具链（awk/sed/jq）处理。对于复杂的数据转换逻辑，它甚至可以先写一个脚本，测试一下，发现有 bug 再修改——整个过程完全自主。
6.4 持续集成中的代码审查
把 Managed Agents 集成到 CI/CD 流水线中，每次 PR 自动触发代码审查：
# 在 CI 脚本中
import anthropic
client = anthropic.Anthropic()
# 复用之前创建的 Agent
session = client.sessions.create(
agent_id="agent_code_reviewer_xxx", # 之前创建好的审查 Agent
environment_id="env_python_dev_xxx",
)
turn = client.sessions.turn.create(
session_id=session.id,
messages=[
{
"role": "user",
"content": f"克隆仓库 {repo_url}，checkout 到 PR 分支 {branch}，"
f"对比 main 分支的 diff，做代码审查。"
f"PR 描述：{pr_description}",
}
],
)
# 拿到审查结果后，通过 GitHub API 发 comment
review_result = turn.response[0].text
post_pr_comment(pr_number, review_result)
这种集成的优势是：Agent 有完整的运行环境，可以不仅看代码 diff，还能编译代码、跑测试、检查依赖——比纯静态分析的代码审查工具强得多。
7. Beta 注意事项
Managed Agents 目前处于 Beta 阶段，有几个重要的注意事项。
7.1 Beta Header
API 请求必须包含 managed-agents-2026-04-01 beta header。如果你用的是官方 Python SDK 或 TypeScript SDK，SDK 在调用 Managed Agents 相关接口时会自动设置这个 header，不需要手动处理。
如果你直接调用 REST API（比如用 curl），需要手动加上：
curl https://api.anthropic.com/v1/agents \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d '{ ... }'
7.2 行为变更
Beta 期间，API 的行为可能在版本间调整。这意味着：
-
工具的输入输出格式可能变化
-
某些参数可能被新增或废弃
-
默认行为可能调整
建议在生产环境中锁定 SDK 版本，升级前先在测试环境验证。Beta 阶段就是这样——用得越早，越需要承受变动的代价。
7.3 速率限制
两个关键限制：
| 操作类型 | 限制 |
|---|---|
| 创建类操作（创建 Agent/Environment/Session） | 300 RPM |
| 读取类操作（查询状态、获取事件） | 600 RPM |
300 RPM 对大部分场景来说足够了。但如果你在 CI/CD 中给每个 PR 都创建 Session，高并发的 mono-repo 可能会碰到上限。解决方案是复用 Session（一个 Session 可以处理多个 PR）或者做请求排队。
7.4 研究预览功能
两个功能目前处于更早期的"研究预览"阶段：
Outcomes（结果评估）：让你定义任务的成功标准，系统自动评估 Agent 的执行结果是否达标。这对于自动化场景特别有用——你不想每次都人工检查 Agent 干得对不对。
Multi-agent（多智能体协作）：多个 Agent 在同一个或不同的 Session 中协作完成任务。类似于 Claude Code 的子代理系统，但在云端、有更丰富的协调机制。
这两个功能需要单独申请访问权限，不包含在标准的 Beta 访问中。如果你的场景需要这些能力，可以通过 Anthropic 的申请通道提交使用场景说明。
小结
Managed Agents 填补了一个空白：可编程的、有状态的、长时运行的 AI 代理。它不是 Claude Code 的替代品，而是把 Claude Code 的能力从本地搬到了云端，并加上了持久化、API 化、容器化的能力。
几个实操建议：
-
先从 Sonnet 开始。Sonnet 的性价比适合大多数场景，只有在需要高推理能力时才切换到 Opus。
-
复用 Agent 和 Environment。创建一次，在多个 Session 中复用。不要每次任务都重新创建。
-
善用 Session 的持久化。一个复杂任务不必在一轮对话中完成。启动 Session，给第一个指令，等结果，再给下一个指令——Agent 始终记得之前的上下文。
-
关注 Beta 变更。订阅 Anthropic 的更新日志，SDK 升级前先在测试环境跑一遍。
-
成本控制从模型选择开始。Token 费用是大头，模型选对了，成本能差一个数量级。