能力地图
语言：English · 中文
这是导航工具：先判断问题属于哪一层，再去对应章节。
十层模型
| 层 | 它回答的问题 | 去哪读 |
|---|---|---|
| 1. 单次请求 | 我能不能从模型拿到一个结构化答案？ | 快速开始、Requests 概览 |
| 2. 稳定输出 | 我每次都能拿到期望的字段吗？ | Schema as Prompt、输出控制 |
| 3. 响应与记忆 | 我能复用一次响应、延续受控窗口对话，或跨 turn 保存任务 records 吗？ | 模型响应、会话记忆、Workspace |
| 4. Action 与执行环境 | 模型是否需要调用函数、MCP server 或带托管执行依赖的沙箱命令？ | Actions 概览、Action Runtime、Execution Environment |
| 5. 知识与服务 | 是否需要检索、HTTP、SSE 或 WebSocket 暴露？ | 知识库、FastAPI 服务封装 |
| 6. 观测与开发 | 是否需要 observation event、DevTools 或 coding-agent 指引？ | 观测概览、Coding Agents |
| 7. Agent 自动编排 | 是否需要一次 Agent turn 在模型响应、Actions、Skills 或 Dynamic Task 候选中选择路线？ | Agent 自动编排 |
| 8. AgentTask loop | 是否需要一个业务任务经过计划、有边界执行、Workspace 证据、验证和 replan？ | Agent 自动编排 |
| 9. 动态任务图 | 是否需要让模型或应用提交 DAG，并在执行前校验它？ | Dynamic Task |
| 10. 编排 | 分支、并发、暂停恢复、持久化 | TriggerFlow 概览 |
每一层都依赖前面的层。跳层是出问题最常见的原因——比如，单次请求没稳定就跳进 TriggerFlow。
路径选择
| 你的处境 | 去哪 |
|---|---|
| 完全新手 | 快速开始 |
| 输出不稳定 / 偶尔缺字段 | Schema as Prompt → 输出控制 |
| 想要字段级流式 UX | Async First → 输出控制 |
| 一次响应想多种方式复用 | 模型响应 |
| 多轮对话且要控制窗口 | 会话记忆 |
| 多轮任务需要持久 observations、artifacts、decisions 或 checkpoints | Workspace |
| 显式 workflow loop 需要持久结构化状态、record links、execution snapshot 查询和 recall | TriggerFlow 概览 + Workspace；见 examples/workspace/workspace_loop_foundation.py |
| 模型要调工具 / MCP | Action Runtime |
| 需要常见 Python / shell / workspace / Node.js / SQLite 能力 | Action Runtime，优先从 agent.enable_python(...)、agent.enable_shell(...)、agent.enable_workspace_file_actions(...)、agent.enable_nodejs(...) 或 agent.enable_sqlite(...) 开始 |
| 需要 web search 或页面 browse | Action Runtime，使用 from agently.builtins.actions import Search, Browse 和 agent.use_actions(...) |
| 执行前需要托管 MCP/sandbox/process/browser/SQLite 生命周期 | Execution Environment，通常面向 action/plugin 开发者 |
| 判断新扩展应该放在哪一层 | 扩展边界 |
| 把 agent 包成服务 | FastAPI 服务封装 |
| 需要查看观测事件 | Event Center → DevTools |
| 需要一次 Agent turn 在模型响应、Actions、Skills 或 Dynamic Task 中选路线 | Agent 自动编排 |
| 单个业务任务需要计划 → 有边界执行 → 证据 → 验证 → replan | Agent 自动编排，从 agent.create_task(...) 开始，并按 AgentExecution result 消费 |
| 模型生成或应用提交的 DAG 需要先校验再执行 | Dynamic Task |
| 多阶段带分支的工作流 | TriggerFlow 概览 → 模式 |
| 长跑流程带人工审批 / 中断 | Pause 与 Resume |
| 跨重启保存恢复 execution | 持久化与 Blueprint |
从 .end() / set_result() / 旧 runtime_data 迁移 | TriggerFlow 兼容 |
决策捷径
- 「我需要 TriggerFlow 吗？」——只在有明确的阶段、分支、并发或暂停恢复时才需要。带重试的单次请求不需要 TriggerFlow。
- 「Dynamic Task 还是 TriggerFlow？」——当图本身是提交上来的数据，需要规划、校验、裁剪和执行时用 Dynamic Task；当你在代码里掌握稳定工作流拓扑时直接用 TriggerFlow。
- 「Sync 还是 async？」——脚本和 demo 用 sync。服务、流式 UI 与 TriggerFlow 用 async。见 Async First。
- 「Action 还是 tool API？」——新代码：
Agently.action/agent.use_actions(...)、来自agently.builtins.actions的内置 package，以及agent.enable_python(...)、agent.enable_shell(...)、agent.enable_workspace_file_actions(...)等场景 helper。已有的tool_func/use_tools/use_mcp/use_sandbox仍可用，但定位为兼容入口；见 Action Runtime。 - 「Agent start 还是显式 API？」——候选驱动的自动编排用
agent.start()；需要路线诊断或过程流式输出时用agent.create_execution()。如果应用必须强制走 Skills 或 Dynamic Task，使用显式agent.run_skills_task(...)或Agently.create_dynamic_task(...)。 - 「AgentTask 还是 TriggerFlow？」——当模型拥有单个业务任务的计划、验证和 replan loop 时，用
agent.create_task(...)；它返回 task-strategyAgentExecution，因此通过 AgentExecution result facade 读取 result/meta/stream/task refs。当应用掌握明确阶段、分支和暂停恢复拓扑时，直接用 TriggerFlow。 - 「Executor 还是 Execution Environment？」——Executor 负责一次调用；Execution Environment 在调用前准备可复用或受 policy 约束的依赖；见 Execution Environment。
- 「Core API 还是语法糖？」——应用开发者应优先使用 built-in actions 和 Agent Component helpers。Core manager 与 provider 面向框架、action、plugin 开发者；见 扩展边界。
- 「Observation event 还是 TriggerFlow event？」——observation event 归 Event Center；
emit/when与 runtime stream 归 TriggerFlow 事件与流。