搭建 Agent 工作流（实操手册）

把一个模糊需求，落成一条能跑、可控、可复现的 Agent 工作流。这篇不讲”什么是编排”（那在 orchestration.md），只讲照着做：从需求到上线的一条施工路径，配一个完整案例。

一句话类比：搭工作流像装修——先量房定需求（目标），再画施工图（DAG），然后一个房间一个房间做（节点），最后验收、留可回退的开关（HITL + 监控）。别一上来就砸墙。

前置概念：Workflow vs Agent 的取舍见 agent.md；编排的核心概念（DAG/State/分支）见 orchestration.md；平台选型（Coze/Dify/n8n）见 agent_dev.md。

0. 先问一句：这事该不该用 Agent？

搭之前先卡这道门，能省掉一半返工：

步骤能写清楚、路径固定 → 纯工作流（代码节点为主，LLM 只在必要处）。
大流程固定、只有某几步”看情况” → 工作流包 Agent（最常见、最稳）。
全程开放、每步都要临场判断 → 才上自主 Agent。

默认倾向：能写死就写死。固定 SOP 硬塞 Agent，既贵又飘（呼应 ai_predictability.md）。

1. 搭建六步法

① 定目标 ──▶ ② 拆步骤 ──▶ ③ 画 DAG ──▶ ④ 选节点类型 ──▶ ⑤ 逐节点实现 ──▶ ⑥ 测试迭代
  一句话      名词化      标依赖         代码/LLM/Agent    prompt+schema    看 trace 调

① 定目标：一句话能说清「输入 → 输出」

写下一句话验收标准：给什么输入、期望什么输出、什么算成功。说不清就先别搭。

✅“输入一条产品新闻链接 → 输出一段 100 字中文摘要 + 3 个标签，发到飞书。”
❌“做一个帮我处理资讯的 AI。“（无法验收）

② 拆步骤：把目标切成动词短句

从输入到输出，列出最少的中间步骤，每步一个动作： 抓网页 → 提正文 → 生成摘要 → 生成标签 → 组装消息 → 发送。经验：一步只干一件事；能合并的别拆碎，能拆开的别塞进一个大 prompt。

③ 画 DAG：标出依赖与分支

把步骤连成有向无环图（不能有环，需要循环用”条件回到某步 + 终止条件”显式控制，见 loop_engineering.md）。标清楚：哪步依赖哪步、哪里有条件分支、哪里可以并行。

抓网页 ─▶ 提正文 ─┬─▶ 生成摘要 ─┐
                  └─▶ 生成标签 ─┴─▶ 组装消息 ─▶ [人审?] ─▶ 发送
                     (两步可并行)              (HITL 开关)

④ 选节点类型：能不用 LLM 就不用

逐个节点问”这步需要理解/生成吗？“——不需要就用代码节点，省钱省时更稳：

节点	该用什么	为什么
抓网页 / 提正文	代码（HTTP + 解析）	确定性逻辑，LLM 是浪费
生成摘要 / 标签	LLM 节点	真需要理解与生成
组装消息	代码（模板拼接）	格式固定
发送	代码（调 API）	确定动作
”这条要不要发”	Agent / 条件	需要判断才上

核心直觉：LLM 只出现在”需要理解或生成”的步骤。整条流水线里 LLM 节点越少，越稳越便宜。

⑤ 逐节点实现：prompt + 结构化输出

对每个 LLM 节点：

写清角色与任务（system + 任务描述），指令强度按需拉满，见 prompt_engineering.md。
强制结构化输出（JSON schema / 固定字段），让下游能稳定接住——这是工作流不崩的关键，见 tool_calling.md、ai_predictability.md。
温度按任务定：要稳定结构化输出就调低温度，别为了”创意”把提取类任务搞飘。
只把这一步需要的上下文喂进去，别把全程历史一股脑塞（context_engineering.md）。

⑥ 测试迭代：看 trace，别看猜

用 3~5 个真实样例跑通，逐节点看输入输出（trace / verbose 日志）。
哪步坏了就地修：先改 prompt/上下文（最便宜），再查节点逻辑，最后才怀疑模型。排障顺序见 agent_dev.md 的”拉哪根杠杆”。
加容错：网络/解析失败重试，超时熔断，关键节点（发消息/写库/花钱）留 human-in-the-loop。

2. 完整案例：资讯摘要发飞书（工作流包 Agent）

用低代码平台（n8n/Dify/Coze）或代码都能落，这里给平台节点视角的施工清单：

[开始:输入链接]
   │
[HTTP 请求] 抓网页 HTML          ← 代码节点，失败重试2次
   │
[代码] 提取正文（去广告/导航）    ← 代码节点
   │
   ├─[LLM] 生成100字摘要          ← 温度0.3，输出 {summary}
   └─[LLM] 生成3个标签            ← 强制输出 JSON {tags:[...]}
   │  (以上两步并行)
[代码] 按模板组装飞书消息         ← 代码节点，拼 {summary}+{tags}
   │
[条件] 摘要是否为空/异常?         ← 空则转人工，不空继续
   │
[人审开关] 首次上线先人审         ← HITL，稳定后再关掉自动发
   │
[HTTP 请求] 调飞书机器人 webhook  ← 代码节点，发送

要点复盘：

6 个节点里只有 2 个用 LLM，其余全是确定性代码 → 稳、便宜。
摘要和标签并行，缩短延迟。
结构化输出（{summary}、{tags:[]}）让”组装消息”能稳定接住。
发送前有条件校验 + 人审开关：上线初期人审，跑稳了再放开自动发。

3. 常见坑

❌ 每步都挂 LLM → 拉数、清洗、拼接、发送都是确定逻辑，用代码节点；LLM 只在理解/生成处出现。
❌ LLM 节点不做结构化输出 → 下游解析全靠猜，工作流一遇到措辞变化就崩。用 JSON schema 兜住。
❌ 图里画了环 → DAG 不能有环；要循环用”条件 + 终止条件”显式控制（loop_engineering.md）。
❌ 没有人审就自动发/写库/花钱 → 关键副作用节点务必留 HITL 或强校验，出错难挽回。
❌ 一上来就上代码/多 Agent → 需求能被平台满足就别下沉；平台卡住了再上 LangGraph（agent_dev.md）。
❌ 不看 trace 瞎调 prompt → 逐节点看输入输出定位坏在哪，再对症下药。

4. 快速自检清单

目标能用”输入→输出→怎样算成功”一句话说清？
步骤拆成了动词短句，一步只干一件事？
画了 DAG，标清依赖/分支/可并行，且无环？
每个节点问过”要不要 LLM”，能用代码的都用了代码？
每个 LLM 节点有结构化输出 + 合适温度？
有副作用的节点留了重试 / 校验 / 人审？
用真实样例跑通并逐节点看过 trace？

5. 延伸阅读 / 关联概念

流程编排（概念） — DAG/State/分支/HITL 的定义；见 orchestration.md
Agent（取舍总纲） — workflow vs agent 怎么选；见 agent.md
AI Agent 开发 — 平台选型（Coze/Dify/n8n）+ 排障拉哪根杠杆；见 agent_dev.md
Loop Engineering — 需要循环时如何设计判停/回步；见 loop_engineering.md
Prompt / Tool Calling — 节点内的指令与结构化输出；见 prompt_engineering.md、tool_calling.md
Context Engineering — 每个节点该喂什么上下文；见 context_engineering.md
AI 可预测性 — 温度/结构化/人为触发让流程稳定；见 ai_predictability.md
用 Agent 团队做独立开发 — 把这套编排落成”四 agent 分工 + Prompt 模板”；见 agent_dev_team.md
小红书发笔记 Agent — 一个”浏览器自动化 + LLM 生成 + HITL + 数据回收”的完整实例；见 xiaohongshu_agent.md

第二大脑 / Knowledge Bank

探索

agent_workflow_build