Agently 开发 Playbook（对齐官方 Agently Skills）
面向使用 Agently 做业务开发的工程师与团队。目标不是再做一份 API 目录，而是把「业务问题 → owner layer → 官方 skill → 文档入口」串成一条可执行路径。
适用范围：Agently 4.x 文档站；本文的路由口径与官方
Agently-Skills保持一致。
1. 先走 skill 路由，再落到文档页
如何阅读这张图
agently-playbook是总入口，用来先判断问题属于请求层、支持能力层、编排层还是迁移层。- 先选最窄的 skill，再去看对应文档；不要一上来就把所有问题都升级成复杂编排。
- 一个真实系统通常会组合多个能力，但 owner layer 只能有一个主入口。
2. Native-first 解题规则
- 先判断是不是一个请求就能解决。
- 能留在请求层，就不要先上 TriggerFlow。
- 先用 Agently 原生能力，不要先发明 wrapper、parser、重试胶水或伪 workflow。
- 只有当分支、并发、等待、恢复、运行态事件本身就是核心问题时，再升级到
agently-triggerflow。 - Tool、MCP、知识库、Session 往往是支持能力，不一定是顶层 owner layer。
3. 场景 -> 官方 skill -> 文档入口
| 业务问题 | 优先 skill | 文档入口 | 说明 |
|---|---|---|---|
| 还没拆清 owner layer / 新项目起步 | agently-playbook | /agent-docs + 当前页 | 先做路由，再进入具体能力层 |
| 模型接入、环境变量、Provider 设置 | agently-model-setup | /model-settings | 先把模型连接与配置边界理顺 |
| Prompt 结构、模板、配置化 Prompt | agently-prompt-management | /prompt-management/overview | Prompt 是请求层能力，不是工作流 |
| 结构化字段、必填键、稳定机读输出 | agently-output-control | /output-control/overview | 优先用 output() / ensure_keys，别先写自定义 parser |
| 流式消费、复用一次结果、读取 text/data/meta | agently-model-response | /model-response/overview | 一次请求多路消费时优先看这里 |
| 多轮连续性、memo、恢复 | agently-session-memory | /agent-extensions/session-memo/ | 会话是请求侧状态，不等于工作流编排 |
| Tools、MCP、FastAPIHelper、KeyWaiter | agently-agent-extensions | /agent-extensions/tools、/agent-extensions/mcp、/agent-extensions/fastapi-helper、/agent-systems/key-waiter | 扩展能力应接在原生表面上，而不是先包一层私有框架 |
| 检索、向量索引、知识库问答 | agently-knowledge-base | /case-studies/kb-dialog | 当前文档站内主要以案例方式展示 KB-to-answer |
| 显式流程、并发、等待/恢复、runtime stream | agently-triggerflow | /triggerflow/overview + /agent-systems/triggerflow-orchestration | 当控制流本身成为核心问题时再升级 |
| LangChain / LangGraph 迁移 | agently-migration-playbook | /agent-docs | 先用官方 migration skills 决定落到 Agent 侧还是编排侧 |
4. 常见组合配方
| 典型系统形态 | 推荐 skill 组合 | 站内入口 |
|---|---|---|
| 工单分诊 / 结构化抽取 | agently-playbook + agently-output-control | /agent-systems/ticket-triage |
| UI 实时展示 + 结构化下游字段 | agently-playbook + agently-output-control + agently-model-response | /agent-systems/streaming-structured |
| 多轮助手 / 偏好记忆 | agently-playbook + agently-session-memory | /agent-systems/session-memo |
| 字段先到先处理 | agently-playbook + agently-agent-extensions | /agent-systems/key-waiter |
| 自然语言控制 / 动作规划与执行 | agently-playbook + agently-output-control + agently-model-response，若需要显式阶段执行再加 agently-triggerflow | /case-studies/talk-to-control |
| 长流程、并发、状态收敛 | agently-playbook + agently-triggerflow | /agent-systems/triggerflow-orchestration |
5. 容易走偏的地方
- 把所有复杂一点的需求都直接归到 TriggerFlow。
- 明明只是结构化输出问题，却先写自定义 JSON parser 和补救逻辑。
- 把“多角色提示词拆分”误当成必须上工作流。
- 把 FastAPI、MCP、控制器接入这类传输或集成层误当成顶层 owner layer。
6. 已有 Playbook 场景页
7. 从 Playbook 走向真实项目
如果你已经完成 owner layer 判断，想看“能力如何落成完整系统”，继续看这些案例：