English mirror
This English page is generated from the current Chinese documentation so every route, anchor, code sample, and language switch stays available on agently.tech. Human-edited English copy can replace this generated body page by page.
企业 Agent 系统设计路线图
很多团队的第一个 AI 原型是一段 prompt。它能演示价值，但很快会遇到几个现实问题：字段进不了业务系统，工具调用没有边界，长流程看不见状态，任务中间产物找不回，版本更新以后无法证明系统真的变好。
Agently 更适合按系统路线来理解：先把模型能力放进工程骨架，再让模型形成可检查的智能回路，之后才开放外部行动、复杂任务资产、长程状态和生产治理。
先按三层问题判断
企业 Agent 的风险通常不是某个 API 没接上，而是交互层、系统行为层和数据层没有分清：
| 层 | 业务问题 | 工程问题 | 推荐入口 |
|---|---|---|---|
| 交互层 | 用户想用自然语言表达目标、追问、补充材料、看过程 | 入口要能把模糊目标变成任务，并把过程事件展示给产品界面或 IM | Agent 自动编排、交互层与主动任务 |
| 系统行为层 | 系统要判断、计划、调用工具、等待审批、失败恢复 | 不能靠长 prompt 或 if / else 把所有路径写死，需要契约、Actions 和流程生命周期 | 输出控制、Actions、TriggerFlow |
| 数据层 | 长任务里有报告、日志、下载物、证据、规则和检查点 | 不能全塞进 Session 或 prompt，要外置保存、按目标和预算召回 | Workspace、长程任务状态与恢复 |
先定位是哪一层的问题，再选择 Agently 能力，会比从“我要不要多 Agent、要不要工作流”开始更稳。
六段能力边界
| 阶段 | 要解决的问题 | 业务上看到什么 | Agently 入口 |
|---|---|---|---|
| 工程骨架 | 模型请求、配置、prompt、业务代码和服务入口混在一起 | 一次 AI 能力可以被 API、脚本或产品界面稳定调用 | 快速开始、项目结构、FastAPI 服务封装 |
| 智能回路 | 模型输出只是文本，代码不知道下一步怎么走 | 分类、计划、风险、待办和回复都变成可消费字段 | 输出控制、工单分流 Playbook |
| 外部行动 | 工具越来越多，模型看到全量能力后容易选错或越权 | 能力有注册、选择、调用记录、权限和错误语义 | Actions、MCP、工具治理与 MCP Host Playbook |
| 复杂任务 | 一条请求里需要多种行为规范、资源和执行策略 | 团队经验可以被选择、加载和复用，而不是散在 prompt 里 | Skills Executor、Dynamic Task |
| 长程状态 | 任务跨轮、跨文件、跨时间推进，context 放不下所有内容 | 产物、证据、检查点和规则可追溯、可召回 | Workspace、长程任务状态与恢复 Playbook |
| 生产治理 | 上线后要定位问题、控制成本、处理审批和回归质量 | 运行事实、评估结果、回放和更新策略能被技术团队管理 | 观测概览、生产治理 Playbook |
这六段不是功能堆叠顺序，而是风险出现顺序。哪一段的问题已经出现，就补哪一层 owner；问题还没出现，不必提前把复杂度搬进项目。
从模型请求到 Agent 系统
先让一次请求稳定
第一步不是多 Agent，也不是工作流，而是让一次请求可重复、可读取、可失败。这里最关键的是三件事：
- 模型设置和业务代码分开，后续可以切换 provider 或运行环境；
- 输出用 schema 固定字段、类型、必填项和 retry；
- 结果通过 result facade 读取 text / data / meta / stream，不为不同视图重复请求模型。
如果这一步没做好，后面接 Actions、TriggerFlow 或 Workspace 都只是在放大不稳定结果。
再把判断变成结构化决策
Agent 的核心不是“多说几句话”，而是把语义判断变成系统能执行的结构。常见结构包括：
| 模式 | 适合问题 | 交付结果 |
|---|---|---|
| 路由 | 输入先分类型、分路径 | category、confidence、dispatch_hint |
| To-Do / 依赖图 | 一个目标要拆成多个子任务 | tasks[]、depends_on[]、执行顺序 |
| Plan / Confirm | 执行前需要看计划或风险 | steps[]、risk、requires_approval |
| Reflection | 输出完成后需要自检和修订 | passed、missing_items、revision_plan |
编排不是替模型做决定，而是规定“在哪一步决定、决定后怎么检查、下游消费什么字段”。
外部行动先接管能力目录
工具少的时候，把函数列表塞进 prompt 也能跑。工具变多以后，系统需要先回答四个问题：
- 系统到底有哪些能力可以用？
- 这次任务应该让模型看到哪些能力？
- 规划逻辑能不能替换成规则、模型、灰度策略或回退策略？
- 本地函数、HTTP、MCP、沙盒进程是否能用同一套执行接口消费？
Agently 的 Actions / Action Runtime / ExecutionEnvironment 对应的是这条链路。MCP 进入这里时，只是多了一类标准化能力来源；Host 侧仍要负责身份透传、可见能力裁剪、脱敏、审批和审计。
复杂任务用资产管理经验
当团队反复处理同一类复杂任务时，经验不应该继续散落在 prompt、README 和代码注释里。Skill 更适合表达“遇到这类问题应该怎么做”：guidance、资源、工具依赖、脚本说明、workflow 描述、输出模板和校验规则。
需要注意边界：Skill 负责被发现、被选择、被加载；真正执行仍回落到 Actions、ExecutionEnvironment、TriggerFlow 或 Dynamic Task。这样做能避免把 Skill 变成第二套 Tool 或 Workflow。
复杂任务里经常还会出现“多 Agent 协作”。官网里不应把它讲成一个新的平行框架模块。更稳的设计是：把角色拆成专门 Agent，把角色任务放进 Sub-Flow，把共享/独立状态放进 Workspace 拓扑，把最终聚合交给父 TriggerFlow。这样业务方看到的是风险审查、事实核验、编辑生成、执行确认等清晰职责，开发者维护的是可测试的子流程和结构化交接字段。需要实施模板时，读 多角色协作与子流程 Playbook。
长程任务先外置状态
模型无状态，context 也有限。跨轮任务里，报告、下载物、审查证据、规则、检查点和中间材料不应该都塞回 prompt。
更稳的结构是：
execution state
只保存紧凑控制数据、阶段、ref、摘要
Workspace
保存 observation、record、artifact、decision、checkpoint
Recall
根据 goal、scope、budget、profile 构建 ContextPack这和 Skill 的渐进式披露是同一个思想：大块内容放在外面，常驻上下文只放引用和必要摘要，用到时按预算取回。
长程任务还要先解决归属：session_id 说明当前对话是谁，task_id 说明这次业务任务是什么，execution_id 说明当前流程跑到哪一次。Session 不是无限 transcript，Workspace 也不是自动长期记忆。更稳的做法是让应用在稳定边界写入 observation、artifact、decision 和 checkpoint，再通过 Recall 把下一步需要的内容打包成 ContextPack。
如果流程要等人工、webhook 或外部系统，就把等待点建成 TriggerFlow interrupt，并把恢复信息交给业务系统持久化。需要补充上下文但不要求流程停下时，用 runtime intervention；两者不要混用。
长任务还需要一个交互层。用户不应该只等最终结果，产品界面、SSE、WebSocket 或 IM 网关应该看到稳定的过程事件：阶段开始、字段完成、材料缺失、等待审批、报告已生成。这里要分清三条通道：产品事件给用户，TriggerFlow signal 改变流程，RuntimeEvent 给运维和评估。需要主动日报、审批提醒、外部 webhook 或 queue worker 时，触发源属于应用系统，Agently execution 负责执行、流式输出、等待和恢复。实施边界见 交互层与主动任务 Playbook。
上线前补齐运行证据
上线不是把功能堆完，而是能回答这些问题：
- 哪个输入触发了哪个 route、哪个 action、哪个 flow chunk？
- 失败发生在模型输出、Action 调用、执行环境、流程等待还是状态恢复？
- 版本更新后，代表性样例是变好了、变差了，还是只是换了一种说法？
- 高风险动作有没有审批、最小权限、审计和 fail-closed 路径？
- 成本、超时、重试、幂等和回放是否有 owner？
没有这些证据，业务方看到的是 demo，技术方承担的是不可定位的生产风险。
常见路线选择
| 当前状态 | 下一步 |
|---|---|
| 只有一段 prompt | 先做 output schema 和 result facade |
| 字段已稳定，但要查业务系统 | 接 Actions，先从一个 mock 或只读能力开始 |
| 工具有 10 个以上 | 建能力注册、按场景激活和执行层归一 |
| 要接 MCP | 先分清 Server / Client / Host，业务治理放 Host |
| 一个任务需要风险、事实、编辑、执行等多角色协作 | 用角色化 Agent + Sub-Flow + Workspace 拓扑，不要让多个模型自由聊天 |
| 流程有分支、并发、等待或过程 UI | 进入 TriggerFlow，而不是继续拉长函数 |
| 任务要跨轮保留报告和证据 | 使用 Workspace artifact + ref，不塞 execution state |
| 要等待人工或外部系统 | 使用 pause_for(...) / continue_with(...)，并保存 execution id 与 pending interrupt |
| 要定时日报、审批提醒或事件驱动任务 | scheduler / webhook / queue 由应用拥有，TriggerFlow execution 承接任务生命周期 |
| 要接前端、IM 或运行过程展示 | 把 runtime stream 映射成稳定产品事件，不把 RuntimeEvent 当 UI 协议 |
| 要证明质量变化 | 建 eval 样例、trace、回放和发布更新策略 |