架构演进目标
Agently 当前演进线要解决的不是“再增加一个 agent 名词”，而是把模型请求、外部能力、长期证据、流程生命周期和观测诊断放进同一条支撑链。官网和文档应该围绕这条链讲能力，而不是把所有功能平铺成同级卖点。
为什么不是只包装模型 API
模型进入软件系统后，它不是一个普通函数，也不是一段更长的 prompt。更合适的工程判断是：模型是一个“不完全可预测、但可以被约束”的计算单元。它能理解自然语言目标、做语义判断、生成计划和调用能力，但它需要外围系统补上契约、状态、权限、流程和验证。
这会改变企业应用的三层设计：
| 层 | 过去常见形态 | AI Agent 场景里的新要求 | Agently 对应能力 |
|---|---|---|---|
| 交互层 | 表单、固定参数、有限消息格式 | 用户用自然语言表达目标，入口要能澄清意图、追问缺失信息、展示过程和建议下一步 | AgentExecution、instant stream、FastAPIHelper、交互层 Playbook |
| 系统行为层 | 预先写死的功能列表和 if / else | 系统要在运行时理解目标、拆步骤、选工具、根据观察继续、等待、回退或终止 | Output Control、Actions、TriggerFlow、Dynamic Task |
| 数据层 | 业务表、日志、Session 历史 | 长任务需要保存证据、artifact、decision、checkpoint，并按目标和预算召回 | Workspace、Recall、ContextPack、RuntimeEvent |
所以 Agently 的重点不是“让模型多说几句”，而是把模型能力接进一套可上线的软件结构：输入和输出有契约，外部行动有边界，流程生命周期可恢复，状态和证据可追溯，运行事实可观察。
再往系统侧看，可以把这套结构拆成四个面：
| 面 | 回答的问题 | 官网表达重点 |
|---|---|---|
| 控制面 | 任务从哪里来、归属谁、按什么权限和策略进入系统 | Gateway、Agent definition、route、policy、服务入口 |
| 执行面 | 系统如何推进目标、调用能力、进入受控环境 | Actions、ExecutionEnvironment、TriggerFlow、Dynamic Task |
| 状态层 | 系统如何保存上下文、产物、恢复点和证据 | Session、Workspace、Recall、checkpoint、artifact refs |
| 治理层 | 系统如何被验证、审批、审计、回放和观测 | Output validation、RuntimeEvent、DevTools、eval、release workflow |
这也是官网内容组织的基本逻辑：先让访问者看到业务系统为什么需要这些层，再把每一层映射到具体 API 和文档。
主线
text
Foundation capabilities
Model request / output control / Actions / ExecutionEnvironment
Workspace / Recall / Exchange-Policy / RuntimeEvent
-> TriggerFlow execution lifecycle
-> BasicFlow / SignalNet / TaskDAG / AdaptiveLoop / BootstrapLoop
-> AgentExecution / SkillsExecution / DynamicTask对应用开发者来说，这条链应该被读成：
- 先用
agent.define(...)保存可复用 Agent 行为。 - 每次
.input(...)、.goal(...)、.output(...)形成一次隔离的 AgentExecution draft。 - 结果通过 AgentExecutionResult 读取 data、text、meta、stream、status 和 diagnostics。
- 需要外部能力时接 Actions；需要托管依赖时接 ExecutionEnvironment。
- 需要长期证据和上下文重建时接 Workspace / Recall。
- 需要清晰流程生命周期时接 TriggerFlow。
- 需要任务图作为输入时使用 TaskDAG / Dynamic Task。
应该强调什么
| 能力 | 官网里的位置 |
|---|---|
| AgentExecution / AgentExecutionResult | 一次 Agent run 的推荐 owner 和 result facade |
agent.define(...) | 可复用定义入口，避免把共享配置和本轮输入混在一起 |
| Output Control / Model Response | 模型结果进入业务系统前的稳定契约 |
| Actions / ExecutionEnvironment | 模型可调用能力和托管依赖生命周期 |
| Workspace / Recall / ContextPack | 多轮证据、artifact、decision、checkpoint 和上下文重建 |
| TriggerFlow | 分支、并发、等待、恢复、stream、save/load 等执行生命周期 |
| RuntimeEvent / EventCenter / DevTools | 执行事实、诊断、观测和服务化调试 |
这些内容应该出现在首页、文档首页、能力地图和核心教程的前半段。
应该降级什么
| 能力或术语 | 正确位置 |
|---|---|
| AgentTask / AgentTaskLoop | AgentExecution 背后的有边界长任务 strategy，不是第二个推荐公开生命周期 |
| Dynamic Task | TaskDAG 的便利 facade，只在任务图作为输入时进入 |
| Skills Executor | guidance、资源和能力包选择层，不重新实现 Actions、ExecutionEnvironment 或 TriggerFlow |
runtime_resources / runtime stream | 当前 API 名可以保留，新架构语言优先使用 execution-local resources / execution stream |
AgentTurn、task_step、.end()、set_result()、旧 tools | 迁移与兼容内容，不作为新手主路径 |
降级不是隐藏这些能力。它的意思是：不要把它们写成普通项目第一步，也不要让读者误以为它们各自拥有一套独立生命周期。
怎么选第一步
| 你遇到的问题 | 先看 |
|---|---|
| 还没跑通模型调用 | 快速开始 |
| 输出不稳定 | 输出控制 |
| Agent 共享配置和本轮输入混在一起 | AgentExecution 与自动编排 |
| 模型需要调用外部能力 | Actions 概览 |
| 多轮任务需要证据和上下文 | Workspace |
| 应用掌握固定流程拓扑 | TriggerFlow 概览 |
| 任务图来自模型或业务系统 | Dynamic Task |
常见判断错误
- 输出契约还没稳定，就先设计 TriggerFlow。流程能跑不代表每个节点的数据可靠。
- 把 Dynamic Task 当 TriggerFlow 的别名。Dynamic Task 处理“任务图作为数据”的场景。
- 把 Skills Executor 当独立运行体系。Skills 应回落到 Prompt、Action、ExecutionEnvironment、资源或 TriggerFlow 模板。
- 把 AgentTask 当新项目默认公开 handle。新代码优先消费 AgentExecutionResult。
- 把 RuntimeEvent 当控制流。TriggerFlow signal 改变流程走向；RuntimeEvent 记录发生了什么。