Agent 系统命题与案例手册（Agently Playbook）
面向使用 Agently 做业务开发的工程师与团队。目标是把「场景 → 需要使用的能力（关键特性）→ 具体操作」串成可执行路径，并配套可运行文档页面（包含代码与输出样例）。
适用版本：Python 3.10 +，Agently 4.0.7.2+。
阅读路径
- 快速上手：看「1. 解题流程」与「2. 场景-功能-操作速查」。
- 能力纠偏：看「3. 容易误用的能力（重点修正）」。
- Playbook 章节：看「4. Playbook 场景库（含代码与输出）」。
1. 解题流程（面向业务开发者）
推荐路径：场景 → 原子命题 → 能力选择 → 具体操作 → 验证
- 场景：用户问题、业务目标、数据输入输出。
- 原子命题：意图识别/结构化抽取/步骤生成/路由/多轮记忆/并发编排/流式输出。
- 能力选择：Output Format + ensure_keys / Session & Memo / TriggerFlow / Streaming。
- 具体操作：落到 Agently 的调用链与代码片段。
- 验证：定义输出结构、关键字段、流式行为、并发/分支结果等验收点。
如果需要更工程化的流程，可参考：Spec → Design → Plan → Dev（先定义输出与验收，再拆任务开发）。
2. 场景-功能-操作速查
| 场景 | 需要使用功能（关键特性） | 具体操作 | 备注 |
|---|---|---|---|
| 意图识别/路由 | 结构化输出（字段稳定） | output() + ensure_keys | 结果接 TriggerFlow 分支 |
| 关键信息抽取 | 结构化输出（列表/嵌套） | output() + ensure_keys | 路径支持 [*] |
| 计划/步骤生成 | 输出顺序控制 | output() 按依赖顺序排列 | 先 facts 再总结 |
| 文本流式 | 文本流式输出 | get_generator(type="delta") | 适合 UI 实时展示 |
| 结构化流式 | Instant 结构化流式 | get_generator(type="instant") | 必须先 output() |
| 节点监听 | KeyWaiter | when_key / wait_keys | 关键字段先到先处理 |
| 多轮对话 | Session & Memo | enable_session_memo() + info(memo) | memo 需显式注入 |
| 编排/并发 | TriggerFlow | to / if / match / for_each / batch | 不只用 when |
| Dify/LangGraph 迁移 | 图结构映射 | chunk=节点，to=边，match/if=路由 | 可快速迁移逻辑 |
3. 容易误用的能力（重点修正）
3.1 输出控制 + 流式输出（正确链路）
python
response = (
agent
.input("...")
.output({"summary": (str,), "items": [(str,)]})
.get_response() # 固定一次请求
)
# 文本流式
for chunk in response.get_generator(type="delta"):
...
# 结构化流式
for item in response.get_generator(type="instant"):
if item.is_complete:
...
# 稳定结构
result = response.get_data(ensure_keys=["summary", "items[*]"])常见错误：
- 未先
output()就用instant→ 无结构化事件。 - 直接在链式调用中反复
get_text()/get_data()→ 触发多次请求。 - 忽略
ensure_keys→ 关键字段偶发缺失导致下游失败。
3.2 TriggerFlow 不只是 when
常见组合：
- 主流程：
to - 条件分支：
if_condition / elif_condition / else_condition - 路由分支：
match / case / case_else - 列表编排：
for_each - 并发执行：
batch+concurrency - 信号驱动：
when(event / runtime_data)
迁移思路（Dify / LangGraph）：
- 节点 →
chunk - 边 →
to - 路由 →
match/if_condition - 状态 →
runtime_data - 并发子图 →
batch/for_each
4. Playbook 场景库（含代码与输出）
以下每个场景都提供完整文档页，含完整代码与真实输出：
- 工单分诊：
/agent-systems/ticket-triage - 流式 + 结构化混合：
/agent-systems/streaming-structured - KeyWaiter 早到字段：
/agent-systems/key-waiter - Session & Memo：
/agent-systems/session-memo - TriggerFlow 编排：
/agent-systems/triggerflow-orchestration
5. 模型配置补充
- 通用模型配置见：
docs/model-settings.md - 具体模型说明见：
docs/models/deepseek.md、docs/models/qwen.md等 - 本地测试可用小模型；复杂系统建议使用云端大模型（效果显著更稳定）
6. 总结
- 场景 → 功能 → 操作 是核心理解路径。
- 输出控制与流式必须一起理解：
output()+instant+ensure_keys。 - TriggerFlow 常用组合是
to + if/match + for_each + batch。
如需面向智能体的执行文档，请看：docs/agent-docs.md。