能力地图

语言：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. 动态任务图	是否需要让模型或应用提交 DAG，并在执行前校验它？	Dynamic Task
9. 编排	分支、并发、暂停恢复、持久化	TriggerFlow 概览

每一层都依赖前面的层。跳层是出问题最常见的原因——比如，单次请求没稳定就跳进 TriggerFlow。

路径选择

你的处境	去哪
完全新手	快速开始
输出不稳定 / 偶尔缺字段	Schema as Prompt → 输出控制
想要字段级流式 UX	Async First → 输出控制
一次响应想多种方式复用	模型响应
多轮对话且要控制窗口	会话记忆
多轮任务需要持久 observations、artifacts、decisions 或 checkpoints	Workspace
显式 workflow loop 需要持久结构化状态、record links、checkpoint 查询和 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 自动编排
模型生成或应用提交的 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(...)。
「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 事件与流。