能力地图
不要先背 Agently 的所有能力名。先看手里的问题属于哪一类，再进入对应章节。
当前文档线的主线是统一 Agent 执行：agent.define(...) 保存可复用行为，每次 .input(...) 生成隔离的 AgentExecution draft，最终通过 AgentExecutionResult 读取数据、文本、流、状态和诊断。Actions、Workspace/Recall、TriggerFlow、Skills 和 Dynamic Task 都挂在这条执行链上，而不是各自形成一套平行运行体系。
如果你还没进入实现，而是在判断“Agently 能不能支撑企业 Agent 上线”，先读 企业 Agent 工程评估。如果要从系统设计角度规划“一次请求如何长成可上线 Agent”，读 企业 Agent 系统设计路线图。如果已经有业务方向，接着读 从场景到能力选型。能力地图回答“该用哪个能力”；工程评估、系统路线和场景选型先回答“为什么需要这一层，以及上线前怎么验收”。
从系统角度看，模型是一个需要被约束和承接的计算单元：交互层要把自然语言目标变成可处理任务，系统行为层要把判断、行动和流程生命周期管起来，数据层要把证据、产物和恢复点放到上下文之外再按需召回。下面的能力选择都围绕这三层展开。
演进目标下的能力层级
Foundation capabilities
Model request / output control / Actions / ExecutionEnvironment
Workspace / Recall / Exchange-Policy / RuntimeEvent
-> TriggerFlow execution lifecycle
-> BasicFlow / SignalNet / TaskDAG / AdaptiveLoop / BootstrapLoop
-> AgentExecution / SkillsExecution / DynamicTask官网和文档应该优先强调这几类能力：
| 优先强调 | 公开表达 |
|---|---|
| AgentExecution / AgentExecutionResult | 一次 Agent run 的推荐 owner 和结果 facade |
agent.define(...) | 可复用 Agent 定义，不和本轮 execution draft 混在一起 |
| Output Control / Model Response | 让模型结果可校验、可复用、可流式消费 |
| Actions / ExecutionEnvironment | Action 暴露模型可调用能力；ExecutionEnvironment 管托管依赖生命周期 |
| Workspace / Recall / ContextPack | 让 observation、artifact、decision、checkpoint 变成可恢复上下文 |
| TriggerFlow / RuntimeEvent / DevTools | TriggerFlow 管执行生命周期；RuntimeEvent 和 DevTools 管观测与诊断 |
这些能力需要降级到高级、策略或兼容语境：
| 需要降级 | 正确表达 |
|---|---|
| AgentTask / AgentTaskLoop | AgentExecution 背后的有边界长任务 strategy，不是第二个推荐公开生命周期 |
| Dynamic Task | TaskDAG 的便利 facade，适合任务图作为输入的场景，不是普通 Agent prompt 的默认入口 |
| Skills Executor | 能力包选择和应用层，不重新实现 Action Runtime、ExecutionEnvironment 或 TriggerFlow |
runtime_resources / runtime stream | 当前 API 可保留，新架构语言优先说 execution-local resources / execution stream |
| 多 Agent | 角色化 Agent + Sub-Flow + Workspace 拓扑的应用设计，不是独立于 AgentExecution / TriggerFlow 的新原语 |
AgentTurn、task_step、.end()、set_result()、旧 tools | 迁移与兼容内容，不进入新手主路径 |
我现在应该用什么
| 当前问题 | 先用什么 | 为什么 | 下一步 |
|---|---|---|---|
| 业务方和技术方一起评估能否上线 | 企业 Agent 工程评估 | 先把稳定输出、受控行动、状态证据、流程生命周期和观测验收说清楚 | 企业 Agent 工程评估 |
| 需要从架构上规划企业 Agent 的成长路径 | 系统设计路线图 | 明确工程骨架、智能回路、外部行动、复杂任务、长程状态和生产治理 | 企业 Agent 系统设计路线图 |
| 已经有工单、日报、文档审查、自然语言控制或专业工作台场景 | 从场景到能力选型 | 先把业务目标映射成能力组合和升级边界 | 从场景到能力选型 |
| 只想跑通一次模型请求 | Quickstart + Request | 先确认模型配置和基本调用可用 | 快速开始 |
| 可复用 Agent 配置和本轮输入开始混在一起 | AgentExecution + Agent definition | agent.define(...) 管长期设置，execution draft 管本轮输入、目标、输出和 options | Agent 自动编排 |
| 模型返回 JSON 不稳定，业务系统不好消费 | Output Control | 把字段、类型、必填项和 retry 先固定住 | 输出控制 |
| UI、SSE 或 workflow 需要在完整响应前看到字段进展 | Instant structured streaming | 用 instant 作为临时 UI / 进度状态，最终仍用 get_data() 读可靠结果 | 输出控制 |
| 同一次响应要读文本、结构化数据、metadata 或流式事件 | Model Response | 一次请求复用多个读取视图，避免重复调用模型 | 模型响应 |
| 模型需要调用函数、MCP、搜索、浏览或沙箱能力 | Actions | Action 是请求期外部能力层，负责调用边界和日志 | Actions 概览 |
| 外部能力需要托管生命周期，比如 MCP server、浏览器、SQLite、Node.js 环境 | Execution Environment | 先准备和复用执行依赖，再交给 Action 调用 | Execution Environment |
| 多轮任务需要记录证据、artifact、decision 或 checkpoint | Workspace / Recall | Workspace 存长期记录，Recall 按目标和预算构建 ContextPack | Workspace |
| 任务跨轮、跨文件、跨审批或跨时间恢复 | 长程任务状态与恢复 | 先分清 Session、Workspace、checkpoint、pause/resume 和 trace 的 owner | 长程任务状态与恢复 Playbook |
| 一个任务需要多个专业角色协作 | 多角色协作与子流程 | 把多角色设计成角色化 Agent、Sub-Flow、Workspace 拓扑和父流程汇总 | 多角色协作与子流程 Playbook |
| 原型脚本要暴露成 HTTP 或流式服务 | FastAPI Helper | 把 request 或 TriggerFlow 包成可消费接口 | FastAPI 服务封装 |
| 用户、前端或 IM 需要看到任务过程 | 交互层与主动任务 | 产品事件、TriggerFlow signal、RuntimeEvent 分开，过程通过 SSE/WebSocket/IM 推送 | 交互层与主动任务 Playbook |
| 系统要定时、webhook 或 queue 主动推进任务 | Scheduler / worker + TriggerFlow | 应用负责触发源、任务表、幂等；Agently execution 负责流程和恢复 | 交互层与主动任务 Playbook |
| 任务图来自模型规划或业务系统提交 | TaskDAG / Dynamic Task | 先校验 DAG，再编译到底层 TriggerFlow 执行 | Dynamic Task |
| 应用掌握流程拓扑，而且有分支、并发、暂停、恢复或持久化 | TriggerFlow | 让应用用 execution lifecycle 管住长流程 | TriggerFlow 概览 |
| 需要看执行过程、事件或调试信息 | Observability / DevTools | 让请求、Action 和流程留下可检查的运行证据 | 观测概览 |
| 准备上线或做版本迭代 | 生产治理 | Eval、Trace、成本、可靠性、安全和更新策略一起验收 | 生产治理 Playbook |
从一次请求开始
大多数项目不需要一上来设计工作流。先把一次请求做成稳定接口：
这三页读完，应用代码就不需要靠手写 JSON parser、重复请求或散落的 prompt 拼接来维持结果稳定。下一步通常是 Agent 自动编排：把长期定义和本轮执行隔离开。
什么时候升级到 Actions
只要模型需要“做事”，就进入 Actions。这里的“做事”包括调用本地函数、MCP tool、搜索、浏览、Python/Bash/Node/SQLite 能力，或访问业务系统的 mock / adapter。
先读 Actions 概览。如果只是给 agent 挂一个函数或内置能力，继续读 Action Runtime。如果需要管理外部进程、浏览器、数据库连接或沙箱生命周期，再读 Execution Environment。
Action 仍然发生在一次 request 内。它不负责长流程的阶段、分支、暂停或恢复。
面向企业落地的边界提醒
| 交付问题 | 错误入口 | 推荐入口 |
|---|---|---|
| 需要按用户身份裁剪模型可见能力 | 直接把全部 MCP tools 暴露给模型 | Host / Action Runtime 先做可见范围和权限边界 |
| 需要让前端实时展示结构化结果 | 自己解析 token 或字符串片段 | instant stream + 稳定 UI event 映射 |
| 需要多个角色共同审查或执行 | 直接“多开几个 Agent 自由聊天” | 角色化 Agent + Sub-Flow + 结构化结果汇总 |
| 需要 IM、前端或主动任务 | 把 observation event 当产品事件 | runtime stream / product event 给用户，Event Center 给运维 |
| 需要执行脚本、浏览器或本地环境 | 在 Action executor 里偷偷启动进程 | ExecutionEnvironment 管生命周期，Action 管调用 |
| 需要高风险动作审批 | 靠 prompt 让模型“谨慎” | TriggerFlow pause/resume 或 policy approval 边界 |
| 需要跨轮保留报告、下载物或检查点 | 塞进 Session 或 execution state | Workspace artifact + ref + Recall ContextPack |
| 需要证明版本改动有效 | 看几次 demo 输出 | 固定 eval 样例、RuntimeEvent trace、业务规则校验和模型 judge |
TaskDAG / Dynamic Task 和 TriggerFlow 怎么选
| 判断 | 用 TaskDAG / Dynamic Task | 用 TriggerFlow |
|---|---|---|
| 流程图是谁决定的 | 模型或应用提交一个 DAG 数据 | 应用代码已经知道稳定拓扑 |
| 先要解决什么 | 任务图是否合法、能不能执行 | 流程运行时怎么开始、分支、等待和结束 |
| 典型场景 | 自动拆解任务、模型规划、业务系统提交任务图 | 审批流、批处理、事件驱动流程、人工介入 |
| 第一篇文档 | Dynamic Task | TriggerFlow 概览 |
说白了：图本身是输入，就用 Dynamic Task；图是应用代码的一部分，就用 TriggerFlow。Dynamic Task 是 TaskDAG 的便利 facade，不负责成为外层长任务 owner。
服务化和观测放在哪
服务化不是最后才补的包装层。只要目标是 API、SSE、WebSocket 或长期运行 worker，先读 Async First。Agently 的 request、result、stream、TriggerFlow 都有 async 路径。
观测也不只用于出问题以后调试。Action logs、RuntimeEvent、execution stream 和 DevTools 能帮团队看到模型请求和流程执行到底发生了什么。服务化路径建议同步读 观测概览。
常见误用
- 输出还不稳定，就直接进入 TriggerFlow。结果是流程能跑，但每个节点的数据都不可靠。
- 把 Action 当工作流。Action 负责一次请求里的能力调用，不负责跨阶段生命周期。
- 把 Dynamic Task 当 TriggerFlow 的别名或长任务 owner。Dynamic Task 处理“任务图作为数据”的场景。
- 把 Skills Executor 当第二套执行器。Skills 应把 guidance、资源和能力映射回 Prompt、Action、ExecutionEnvironment 或 TriggerFlow。
- 把多 Agent 当框架魔法原语。实际要设计的是角色、交接字段、状态拓扑和父流程汇总。
- 把 IM / 前端事件、TriggerFlow signal 和 RuntimeEvent 混成一条通道。产品体验、流程控制和运维观测要分开。
- 把 AgentTask 当新项目的默认公开 handle。新代码优先消费 AgentExecutionResult。
- 在服务端继续写同步 demo 代码。服务和流式路径应优先 async。
- 把兼容 API 当新项目推荐入口。旧 tools、
.end()、set_result()等先去 术语表 的兼容分组确认状态。
下一步
- 第一次试用：快速开始
- 正在整理 Agent 主线：Agent 自动编排
- 正在做外部能力：Actions 概览
- 正在做长程任务：长程任务状态与恢复 Playbook
- 正在做多角色协作：多角色协作与子流程 Playbook
- 正在做过程输出或主动任务：交互层与主动任务 Playbook
- 正在做上线治理：生产治理 Playbook
- 正在做长流程：TriggerFlow 概览
- 正在迁移旧项目：术语表