Claude Managed Agents
概述
Claude Managed Agents 是 Anthropic 推出的托管智能体执行平台——一套开箱即用、可配置的智能体运行框架（harness），运行于托管基础设施之上。开发者无需自行搭建智能体循环、工具执行层和运行时，即可获得完整的托管环境：Claude 可在其中读取文件、执行命令、浏览网页并安全地运行代码。平台内置提示词缓存、上下文压缩及其他性能优化能力。
该平台于 2026 年 4 月至 5 月间宣布新增三项能力：Memory（记忆）（公测，4 月 23 日）、Dreaming（梦境）（研究预览，5 月 6 日）以及 Outcomes + Multiagent Orchestration（成果 + 多智能体编排）（公测，5 月 6 日）。
基本要求：所有 Managed Agents API 请求均需携带 managed-agents-2026-04-01 beta 头。SDK 会自动设置该头。
核心概念
| 概念 | 说明 |
|---|---|
| Agent（智能体） | 模型、系统提示词、工具、MCP 服务器及技能的集合——定义一次，通过 ID 复用 |
| Environment（环境） | 会话的运行位置：Anthropic 托管的云容器或自托管沙箱 |
| Session（会话） | 正在执行特定任务的智能体实例，产生事件流 |
| Events（事件） | 应用与智能体之间交换的消息（用户回合、工具结果、状态信息等） |
功能一 — Memory（记忆，公测）
简介
记忆存储（memory store）允许智能体跨会话保留信息：用户偏好、项目规范、历史错误以及领域背景知识。默认情况下，每个会话独立启动；若不启用记忆，所有状态会在会话结束后丢失。
记忆存储是一个工作区级别的文本文档集合。挂载到会话后，它将以目录形式挂载到容器内的 /mnt/memory/ 路径下。智能体使用与访问其他文件系统相同的文件工具（bash、grep 等）对其进行读写。系统提示词中会自动附加一条说明，描述每个挂载点的路径、访问模式、描述及操作说明。
每次修改都会生成一个不可变的记忆版本（memver_...），提供完整的审计轨迹和时间点恢复能力。版本保留 30 天（近期版本无论时间长短均会保留）。
关键限制
| 限制项 | 值 |
|---|---|
| 每个会话最多挂载记忆存储数量 | 8 个 |
| 单个记忆文件最大大小 | 100 kB（约 25k tokens） |
| 每个存储的操作说明最大长度 | 4,096 字符 |
| 记忆版本保留时间 | 30 天（近期版本始终保留） |
API
创建存储 — POST /v1/memory_stores
store = client.beta.memory_stores.create(
name="User Preferences",
description="Per-user preferences and project context.",
)
# store.id = "memstore_01Hx..."
首次会话前预填内容（可选）：
client.beta.memory_stores.memories.create(
store.id,
path="/formatting_standards.md",
content="All reports use GAAP formatting. Dates are ISO-8601...",
)
挂载到会话 — 指定 access 和各存储的 instructions：
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
resources=[{
"type": "memory_store",
"memory_store_id": store.id,
"access": "read_write", # or "read_only"
"instructions": "User preferences and project context. Check before starting any task.",
}],
)
安全内容编辑 — 使用 content_sha256 实现乐观并发控制，避免并发写入冲突：
client.beta.memory_stores.memories.update(
memory_id=mem.id,
memory_store_id=store.id,
content="CORRECTED: Always use 2-space indentation.",
precondition={"type": "content_sha256", "content_sha256": mem.content_sha256},
)
版本脱敏（合规用途——从历史记录中删除 PII/密钥）：
client.beta.memory_stores.memory_versions.redact(version_id, memory_store_id=store.id)
记忆结构最佳实践
记忆应组织为多个小型、专注的文件，而非少数几个大文件（每文件上限 100 kB）。使用目录路径按主题分类：
/preferences/formatting.md
/preferences/communication-style.md
/project/architecture-decisions.md
/project/known-issues.md
安全警告
记忆存储默认以 read_write 权限挂载。若智能体处理不可信输入（用户提示词、抓取的网页内容、第三方工具输出），提示词注入攻击可能将恶意内容写入存储，后续会话则会将其作为可信记忆读取。对于参考资料、共享查找表以及任何无需智能体修改的存储，请使用 read_only 权限。
功能二 — Dreaming（梦境，研究预览）
简介
Dreaming 是一种异步记忆整理任务，在两次会话之间运行，而非在任务执行期间运行。它以记忆存储和历史会话记录为输入，输出一个经过重新整理的新记忆存储——输入内容从不被修改（设计上为非破坏性操作）。
其类比是海马体的记忆巩固机制：Dreaming 不会无限期保存原始交互记录，而是回顾累积的内容，去重、消除矛盾与过时信息，并将反复出现的模式（重复的错误、团队偏好）提炼为结构化的干净记忆。
所需额外 beta 头：dreaming-2026-04-21
Dreaming 的功能
- 将重复信息合并到已有的主题文件中（而非创建新的近似重复内容）
- 删除或替换过时、相互矛盾的条目，保留最新值
- 挖掘新洞察与反复出现的模式：偏好的工作流、重复的错误、团队规范
- 将相对日期转换为绝对日期，以提升时间信息的持久性
- 输出整洁的、带索引的主题文件结构
API
创建 dream — POST /v1/dreams
dream = client.beta.dreams.create(
inputs=[
{"type": "memory_store", "memory_store_id": store_id},
{"type": "sessions", "session_ids": [session_a, session_b]},
],
model="claude-opus-4-7",
instructions="Focus on coding-style preferences; ignore one-off debugging notes.",
)
# dream.id = "drm_01..."
# dream.status = "pending"
追踪进度（轮询）：
while dream.status in ("pending", "running"):
time.sleep(10)
dream = client.beta.dreams.retrieve(dream.id)
使用输出 — 输出即为普通记忆存储；审核后可挂载到后续会话：
output_store_id = next(
o.memory_store_id for o in dream.outputs if o.type == "memory_store"
)
session = client.beta.sessions.create(
agent=agent_id,
environment_id=environment_id,
resources=[{"type": "memory_store", "memory_store_id": output_store_id}],
)
取消 / 归档 — 支持标准的生命周期管理操作。
Dream 生命周期
| 状态 | 含义 |
|---|---|
pending |
已创建并加入队列 |
running |
流水线处理中；usage 实时更新 |
completed |
输出记忆存储已就绪 |
failed |
因错误终止；输出存储包含部分结果 |
canceled |
手动取消；输出存储包含部分结果 |
运行期间，dream.session_id 指向执行该流水线的底层会话——可以流式订阅该会话的事件，实时观察 dream 的读写过程。
限制与计费
| 限制项 | 值 |
|---|---|
| 每个 dream 最多包含的会话数 | 100 |
instructions 长度 |
4,096 字符 |
| 支持的模型 | claude-opus-4-7、claude-sonnet-4-6 |
| 典型运行时长 | 数分钟至数十分钟 |
| 计费 | 按标准 Token 费率计算；随会话数量和长度线性增长 |
错误类型
error.type |
触发条件 |
|---|---|
timeout |
超出运行时间预算 |
internal_error |
未分类的流水线故障 |
memory_store_org_limit_exceeded |
在预配期间组织触达记忆存储上限 |
input_memory_store_too_large |
输入存储超出流水线大小限制 |
input_memory_store_unavailable |
dream 创建后输入存储被归档或删除 |
input_session_unavailable |
dream 创建后某个输入会话被归档或删除 |
功能三 — Outcomes（成果，公测）
简介
Outcomes 将会话从对话升级为目标导向的工作模式。你通过一份自然语言评分标准（rubric）定义"完成"的标准。运行框架自动为智能体输出分配一个独立的评分器（grader），依据评分标准评估输出结果、返回逐条反馈，智能体持续迭代，直至满足成果要求或达到 max_iterations 上限。
评分器在独立的上下文窗口中运行，与主智能体的推理过程隔离，从而防止智能体的实现选择污染评估结果（与评测框架中的 LLM 充当评审原则相同）。
评分标准设计
评分标准是一份包含明确、可评分标准的 Markdown 文档。每项标准独立评分，因此标准模糊会导致评估噪声较大。
# DCF Model Rubric
## Revenue Projections
- Uses historical revenue data from the last 5 fiscal years
- Projects revenue for at least 5 years forward
## Discount Rate
- WACC is calculated with stated assumptions
- Beta, risk-free rate, and equity risk premium are sourced or justified
## Output Quality
- All figures in a single .xlsx file with clearly labeled sheets
- Sensitivity analysis on WACC and terminal growth rate included
Anthropic 的建议：提供一份已知高质量的示例产出，让 Claude 分析其优质之处，再将分析结果转化为评分标准——这种方式通常比从零开始撰写标准效果更好。
评分标准可以以文本形式内联传入，也可以通过 Files API 上传一次后，凭文件 ID 在多个会话中复用。
API
定义成果 — 在会话创建后发送 user.define_outcome 事件：
session = client.beta.sessions.create(agent=agent.id, environment_id=environment.id)
client.beta.sessions.events.send(
session_id=session.id,
events=[{
"type": "user.define_outcome",
"description": "Build a DCF model for Costco in .xlsx",
"rubric": {"type": "text", "content": RUBRIC},
# or: "rubric": {"type": "file", "file_id": rubric.id},
"max_iterations": 5, # optional; default 3, max 20
}],
)
智能体在收到事件后立即开始工作，无需额外消息触发。
成果事件
| 事件 | 说明 |
|---|---|
span.outcome_evaluation_start |
评分器开始评估某次迭代，iteration 字段从 0 开始计数 |
span.outcome_evaluation_ongoing |
评分器运行期间的心跳事件；内部推理过程不透明 |
span.outcome_evaluation_end |
评分器完成评估；result 字段指示下一步操作 |
span.outcome_evaluation_end 的 result 值：
result |
后续行为 |
|---|---|
satisfied |
会话转为 idle 状态 |
needs_revision |
智能体开始新一轮迭代 |
max_iterations_reached |
智能体可执行最后一次修订；会话转为 idle 状态 |
failed |
评分标准与任务根本不匹配（例如描述与标准相互矛盾）；会话转为 idle 状态 |
interrupted |
评估开始后收到了 user.interrupt 事件 |
评估结束事件示例：
{
"type": "span.outcome_evaluation_end",
"outcome_id": "outc_01a...",
"result": "satisfied",
"explanation": "All 12 criteria met: revenue projections use 5 years of historical data, WACC assumptions are stated...",
"iteration": 0,
"usage": {"input_tokens": 2400, "output_tokens": 350}
}
获取交付物
智能体将输出文件写入容器内的 /mnt/session/outputs/ 目录。通过限定会话范围的 Files API 获取：
files = client.beta.files.list(scope_id=session.id)
content = client.beta.files.download(files.data[0].id)
content.write_to_file("/tmp/output.xlsx")
链式成果
同一时间只有一个成果处于活跃状态。当一个成果的终止事件发出后，可再次发送 user.define_outcome 来链式定义下一个成果。会话会保留历史成果的记录。
功能四 — Multiagent Orchestration（多智能体编排，公测）
简介
多智能体编排允许一个协调者（coordinator）智能体将复杂任务拆分并分派给各专家（specialist）智能体，各专家在各自隔离的上下文中并行运行。待专家完成后，协调者负责汇总结果。
架构
- 所有智能体共享同一个容器、文件系统和 vault 凭据（共享状态）
- 每个智能体在各自的会话线程中运行——拥有独立的上下文事件流和对话历史
- 线程具有持久性：协调者可向之前调用过的智能体继续发送消息
- 每个智能体使用自己的配置（模型、系统提示词、工具、MCP 服务器、技能）——上下文不跨智能体共享
- MCP 服务器以智能体为作用域；vault 凭据以会话为作用域（在所有线程间生效）
配置
在协调者智能体上设置 multiagent.type = "coordinator"，并配置专家名单：
coordinator = client.beta.agents.create(
name="Engineering Lead",
model="claude-opus-4-7",
system="Coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.",
tools=[{"type": "agent_toolset_20260401"}],
multiagent={
"type": "coordinator",
"agents": [
{"type": "agent", "id": reviewer_agent.id},
{"type": "agent", "id": test_writer_agent.id},
{"type": "self"}, # coordinator can also spawn copies of itself
],
},
)
名单条目：
- {"type": "agent", "id": agent_id} — 按 ID 引用（固定为最新版本）
- {"type": "agent", "id": agent_id, "version": v} — 固定特定版本
- {"type": "self"} — 协调者生成自身的副本
限制
| 限制项 | 值 |
|---|---|
| 最大并发线程数 | 25 |
| 名单中最多不同智能体数 | 20 |
| 最大委派深度 | 1 层（协调者 → 专家；专家不可再次委派） |
协调者可在名单中多次调用同一智能体（每次调用创建一个新线程）。
委派模式
| 模式 | 说明 |
|---|---|
| 并行化 | 同时展开独立子任务（搜索多个来源、分析不同文件），再汇总结果 |
| 专业化 | 将任务路由到具有特定领域提示词和工具的智能体（安全智能体、文档智能体） |
| 升级处理 | 针对特定复杂子任务，委托给能力更强的模型处理 |
线程事件（主事件流）
| 事件 | 说明 |
|---|---|
session.thread_created |
线程已创建；包含 session_thread_id 和 agent_name |
session.thread_status_running |
线程开始活动 |
session.thread_status_idle |
智能体等待输入；包含 stop_reason |
session.thread_status_terminated |
线程已归档或出现终止性错误 |
agent.thread_message_received |
专家智能体向协调者返回结果 |
agent.thread_message_sent |
协调者向专家智能体发送后续消息 |
子智能体发出的工具权限请求（requires_action）会被转发到主线程。以 user.tool_confirmation（携带 tool_use_id）响应——服务器会自动将其路由到对应线程。
自我改进循环（组合使用）
Memory + Dreaming + Outcomes 组合构成一个复合自我改进循环：
Session executes task
↓
Outcomes grader evaluates against rubric (separate context)
→ needs_revision? Agent iterates
→ satisfied? Session completes
↓
Agent writes observations, preferences, patterns to memory store during session
↓
[Between sessions] Dreaming job runs:
- Ingests episodic logs from past sessions + current memory store
- Deduplicates, removes stale facts, promotes recurring patterns
- Produces new consolidated memory store
↓
Next session starts with enriched, curated memory
→ Agent has inherited behavioral improvements without model retraining
这是 Anthropic 对 CoALA 分类法中"反思/巩固长期记忆（LTM）"策略的生产级实现。整个过程无需对模型进行微调或更新权重——改进完全通过记忆整理实现。
生产案例：Harvey（法律 AI 初创公司，试点客户）报告称，在法律文书工作流中采用此组合循环后，任务完成率提升了约 6 倍（2026 年 5 月）。
可用性
| 功能 | 状态 | Beta 头 |
|---|---|---|
| Memory（记忆） | 公测 | managed-agents-2026-04-01 |
| Outcomes（成果） | 公测 | managed-agents-2026-04-01 |
| Multiagent Orchestration（多智能体编排） | 公测 | managed-agents-2026-04-01 |
| Dreaming（梦境） | 研究预览（需申请） | managed-agents-2026-04-01,dreaming-2026-04-21 |
注意：Claude Managed Agents 在设计上为有状态服务，不符合零数据保留（ZDR）或 HIPAA BAA 的覆盖条件。会话、文件和记忆存储均可通过 API 删除。
速率限制
| 操作 | 限制 |
|---|---|
| 创建端点（agents、sessions、environments 等） | 300 次请求/分钟 |
| 读取端点（retrieve、list、stream 等） | 600 次请求/分钟 |
最佳实践
| 挑战 | 说明 | 建议 |
|---|---|---|
| 评分标准模糊 | 标准不明确会导致评分噪声较大 | 编写明确、可量化的标准：例如"CSV 包含一列数值类型的价格列"，而非"数据看起来不错"。使用已知高质量产出来生成标准。 |
| 记忆文件过大 | 大型单一记忆文件触达 100 kB 上限，降低相关性 | 在 /mnt/memory/ 下将记忆组织为多个小型主题文件，并使用目录层次结构 |
| 记忆遭提示词注入 | read_write 存储处理不可信输入 → 恶意记忆被写入 |
对参考类存储使用 read_only；隔离处理用户输入内容的存储 |
| Dreaming 数据质量差 | 记忆组织混乱导致整理输出质量低 | 在运行 dream 前先按主题组织初始记忆；提供 instructions 聚焦 dreaming 范围 |
| 多智能体 Token 预算 | 并行专家可能导致总成本膨胀 | 为每个专家选用能胜任任务的最小模型（例如用 Haiku 做研究、用 Opus 做推理）；控制名单规模 |
| 评分器上下文污染 | 评分器看到智能体推理过程会破坏隔离性 | 绝不将智能体的草稿或思维链传递给评分器——独立上下文窗口已从机制上强制执行此约束 |
| 并发记忆写入 | 多个智能体共享 read_write 存储产生竞态条件 |
在更新时使用 content_sha256 前置条件；考虑为每个智能体线程单独分配存储 |
| 最大迭代次数调优 | 过少导致提前终止；过多导致成本失控 | 从默认值（3）开始，仅在已知高修订周期的任务中提高；在事件中监控 iteration 字段 |
参见
参考资料
- New in Claude Managed Agents: dreaming, outcomes, and multiagent orchestration — Anthropic 官方博客，2026 年 5 月
- Memory and dreaming for self-learning agents — YouTube 视频，Anthropic，2026 年
- Using agent memory — Claude API Docs — 官方 Memory 文档
- Dreams — Claude API Docs — 官方 Dreaming 文档
- Define outcomes — Claude API Docs — 官方 Outcomes 文档
- Multiagent sessions — Claude API Docs — 官方多智能体文档
- Claude Managed Agents overview — Claude API Docs — 平台概览