【Claude基础】09.多代理协作：Agent Teams与编排模式

1. Managed Agents vs Claude Code 子代理
1.1 定位区分
1.2 选择标准
1.3 决策矩阵
1. 四要素架构模型
2.1 Agent --- 定义"谁来干活"
2.2 Environment --- 定义"在哪干活"
2.3 Session --- 定义"一次干活过程"
2.4 Events --- 定义"怎么交流"
1. 完整工作流程
3.1 五步流程
3.2 Python SDK 代码示例
3.3 中途引导
1. 内置工具
4.1 Bash --- 容器内 Shell
4.2 文件操作
4.3 Web Search / Web Fetch
4.4 MCP 服务器接入
1. 定价模型详解
5.1 Token 费用
5.2 Session 运行时
5.3 成本计算示例
5.4 与自建基础设施的成本对比
1. 适用场景分析
6.1 大规模代码迁移
6.2 自动化测试生成
6.3 数据处理流水线
6.4 持续集成中的代码审查
1. 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 中的一次运行实例。它有明确的生命周期：

bash 复制代码

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 到接收结果：

bash 复制代码

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 回复完毕。")

如果你不需要流式接收，也可以用同步方式等待结果：

bash 复制代码

# 同步方式------等待完成后一次性获取结果
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 会基于之前的上下文继续工作：

bash 复制代码

# 第一轮：审查代码
# ...（如上）

# 第二轮：基于审查结果修复
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

bash 复制代码

{"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

bash 复制代码

{"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 的能力边界。

bash 复制代码

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：

bash 复制代码

输入 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

bash 复制代码

输入 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 命中了缓存：

bash 复制代码

缓存命中 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 任务、日志分析、数据清洗------这些任务的共同特点是"给一堆数据，按规则处理，输出结果"：

bash 复制代码

# 创建数据处理 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 自动触发代码审查：

bash 复制代码

# 在 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 阶段，有几个重要的注意事项。

API 请求必须包含 managed-agents-2026-04-01 beta header。如果你用的是官方 Python SDK 或 TypeScript SDK，SDK 在调用 Managed Agents 相关接口时会自动设置这个 header，不需要手动处理。

如果你直接调用 REST API（比如用 curl），需要手动加上：

bash 复制代码

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 费用是大头，模型选对了，成本能差一个数量级。

【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 研究预览功能

小结