背景与动机
Managed Agent API 的关键不是“再包一层聊天接口”，而是把 Agent 的定义、执行环境、会话状态和事件流拆开管理。
这样做的好处是：配置可以版本化，环境可以隔离，会话可以持久化，执行过程可以被观察。
四个核心概念
1. Agent
Agent 表示“这个智能体是谁、能做什么、遵守什么规则”。它通常包含：
- 模型选择。
- 系统提示。
- 工具列表。
- 行为约束。
- 输出格式要求。
Agent 更像配置定义，不应该混入每次会话的临时状态。
2. Environment
Environment 表示 Agent 执行动作的环境。它可以包含：
- 文件系统。
- 命令执行权限。
- 网络访问。
- 环境变量。
- 沙箱策略。
Environment 的重点是隔离和权限。
3. Session
Session 表示一次连续任务或对话。它保存：
- 用户目标。
- 多轮上下文。
- 工具调用结果。
- 当前状态。
Session 让 Agent 可以跨多轮保持任务连续性。
4. Events
Events 表示执行过程中的事件流。例如：
- 模型开始响应。
- 工具调用开始。
- 工具调用结束。
- 出错。
- 任务完成。
事件流让前端、日志系统和调试工具能看到 Agent 在做什么。
一次调用链路
典型链路：
创建或选择 Agent ↓绑定 Environment ↓创建 Session ↓用户发送任务 ↓Agent 决策并调用工具 ↓Environment 执行动作 ↓Events 持续输出状态 ↓Session 保存结果常见陷阱
- 把 Agent 定义和 Session 状态混在一起。
- Environment 权限过宽。
- 只返回最终文本，不记录中间事件。
- Session 不可追踪，出了问题无法复盘。
为什么要拆成四块
如果不拆：
- Agent 定义会混进每次对话状态。
- Environment 权限无法按任务隔离。
- Session 失败后无法恢复。
- Events 不完整会导致调试只剩最终结果。
拆开以后，同一个 Agent 可以跑在不同环境里，同一个 Session 可以回放，同一套事件可以给前端、日志和监控复用。
生图提示词
建议插入在 ## 四个核心概念 前面。
文件名建议：image/02-managed-agent-api-model-01.png
插入 Markdown：
生图提示词：
画一张 Managed Agent API 四大概念架构图，浅色背景。中心是一次用户任务，周围四个模块：Agent 定义、Environment 环境、Session 会话、Events 事件流。Agent 指向模型和工具列表，Environment 指向文件系统和命令权限，Session 指向上下文和状态，Events 指向前端和日志系统。用箭头表示一次调用链路。中文标签，清晰的系统架构图。一句话总结
Managed Agent API 的重点是把“定义、环境、会话、事件”拆开，让 Agent 任务可以被管理、观察和复用。