小白如何开始开发一个 Agent：从需求到最小闭环

如果你刚开始接触 Agent，先别急着选模型或搭框架。先弄清楚要解决的工作是什么，以及它是否真的需要 Agent。

可以把 Workflow 和 Agent 简单理解成：

• **Workflow：**人提前把步骤和分支设计好，系统照着执行。
• **Agent：**人给目标和边界，系统在运行时根据情况判断下一步、选择工具，并检查结果。

比如做一个“抖音店铺客服”：

Workflow 版：

1. 识别用户问题属于哪一类；
2. 查询对应商品资料；
3. 按模板生成回答；
4. 遇到退款或投诉就转人工。

流程是你预先设计好的，模型主要负责其中的分类、检索或措辞。

Agent 版：

目标是“尽可能解决用户问题，同时遵守退换货规则”。系统先判断还缺什么信息，再决定查询订单、查商品资料、调用售后接口，必要时追问用户；处理后检查问题是否解决，超出权限或有风险时转人工。

核心差异不是“有没有调用大模型”，而是运行时谁决定下一步。当然，真实系统通常是混合的：外围用 Workflow 控制权限、顺序和兜底，局部让 Agent 处理需要判断的部分。

小白从需求开始，按这 7 步走

1. 先找一个具体、重复的工作

别从“我要做一个 Agent”开始，而从一句具体的话开始：

现在是谁，在什么情况下，需要完成什么工作？最麻烦的环节是什么？

例如：

抖店客服每天要回答大量重复的商品问题；商品资料散落在多个文档里，查找慢，回答不一致。

2. 把需求写成一个任务

用这个句式：

当【触发条件】出现时，系统帮助【使用者】完成【任务】，达到【可衡量结果】；遇到【风险或例外】时，采取【兜底动作】。

例如：

当用户咨询商品尺码时，系统根据商品资料和用户提供的信息推荐合适尺码，回答必须有资料依据；如果资料不足或涉及退换货承诺，就追问或转人工。

这一步会帮你判断：问题是否足够明确，Agent 是否真的有必要。

3. 先把人现在怎么做写出来

问自己或实际操作者：

• 他先看什么？
• 根据什么做判断？
• 信息不够时会追问什么？
• 什么时候需要查系统、表格或知识库？
• 什么情况必须交给人？
• 出错会造成什么后果？

尽量写真实步骤，不要先想“Agent 应该多聪明”。

4. 把任务拆成三类

任务环节	适合的做法
步骤固定、规则明确	Workflow、代码、API
需要理解文字、归类、提取信息	大模型节点
下一步取决于当前结果，需要规划或选工具	Agent

一个实用原则是：**能用固定规则稳定解决的，就先别交给 Agent 自由决策。**例如权限检查、退款上限、是否允许发券，应该由确定规则控制。

5. 从最小闭环开始

先做一个能完成单一任务的版本：

输入 → 理解请求 → 查必要信息 → 生成结果 → 检查 → 人工确认或完成

第一版可以不让它自动执行有风险的操作。比如先生成客服回复草稿，让人工确认；确认准确后，再逐步开放低风险动作。

6. 用真实案例测试，而不是只看演示

收集几十条真实请求，至少包含：

• 常见问题；
• 信息缺失；
• 用户表达含糊；
• 知识库没有答案；
• 多个问题混在一起；
• 越权要求或高风险情况。

检查的不只是“回答像不像人”，还要看：

• 任务完成了吗？
• 答案有没有依据？
• 是否调用了正确工具？
• 该追问或转人工时做了吗？
• 有没有擅自承诺或执行？

7. 看结果再决定要不要加 Agent

如果流程已经很稳定，Workflow 就够了。如果大量请求需要根据上下文改变步骤、挑选工具或补充信息，再把那一段交给 Agent。不要为了让产品听起来更先进，把整个系统都改成 Agent。

一句话判断

可以问自己：

如果我能把所有步骤和分支提前写清楚，它更像 Workflow；如果系统必须根据运行时信息决定下一步，它才需要 Agent。

所以，你现在做出 Workflow 并不说明方向错了。它往往是最好的起点：先把流程跑通、积累真实案例，再找出那些确实需要动态判断的环节，把它们逐步升级成 Agent。

用 Codex 从零开发 Agent：小白操作手册

这是一份可以照着执行的项目流程。你不需要先学会所有 Agent 术语；按照每阶段的提示词和产物，与 Codex 一步一步确认需求、选择实现方式、生成项目文件、开发和测试。

本手册会帮助你判断最终应该做成：普通程序、单独的 Tool、Workflow、局部 Agent，还是 Agent 主导的系统。

使用方法

1. 在 Codex 中打开一个新的项目目录，或者打开已有代码项目。
2. 把本手册中的提示词分阶段发给 Codex。
3. 每一阶段先确认结论，再进入下一阶段。
4. 如果 Codex 的结论和你的实际业务不符，纠正它，并要求更新需求记录。
5. 在需求和架构确认之前，不要让 Codex直接开始大量写代码。
6. 每个阶段都要求 Codex 把确认结果保存到项目文件中，避免只留在聊天记录里。

需求访谈 → 工作流程卡 → 技术方案判断 → 项目文件 → 分阶段开发 → 测试验收 → 小范围试用 → 复盘迭代

第一阶段：和 Codex 说明你的目标

目标

告诉 Codex 你是初学者，希望它先帮助你弄清楚需求，而不是直接写代码。

第一次发给 Codex 的提示词

我想用 Codex 开发一个能解决真实问题的 AI 功能。我是 Agent 开发小白，暂时不确定应该做 Agent、Workflow、单独的 Tool，还是普通程序。

请先担任我的需求分析和技术设计导师，不要立即写代码。请按阶段访谈我，一次只进行一个阶段，每轮只问我 1 到 3 个最关键的问题。

要求：
1. 用通俗中文解释概念，不默认我懂技术术语。
2. 先了解我想解决的真实工作问题，再讨论技术方案。
3. 不要替我编造用户、业务事实、数据来源、接口能力或成功指标。
4. 我说“不知道”时，用例子、选项或让我描述最近发生的一次真实情况来帮助我回答。
5. 每个阶段结束后，先总结已确认信息、未确认信息和阶段结论。
6. 每次阶段结论都保存到项目中的 docs/ 目录；如果目录不存在就创建。
7. 在完成需求分析、流程分析和技术方案判断之前，不要写实现代码。
8. 不要默认必须使用 Agent。最终可以得出普通程序、单独 Tool、Workflow、局部 Agent 或 Agent 系统。
9. 如果我纠正了结论，接受纠正并更新文档，不要把未经确认的假设写成事实。
10. 先从第一阶段开始：帮助我说清楚我想解决什么问题。

如果你还不知道要做什么

把这段发给 Codex：

我还说不清楚。请不要让我先想技术方案。请给我一些常见场景选项，例如自动整理资料、回答重复问题、生成内容、查询业务数据、处理多步骤工作、操作网站或软件。然后让我选一个最接近的场景，并用最近发生的一件具体事情帮助我把需求说清楚。

第二阶段：和 Codex 做需求访谈

目标

把“我想做个 Agent”转成一个具体、可判断、可验收的业务任务。

发给 Codex 的提示词

现在进入需求访谈阶段。请一次问我 1 到 3 个问题，直到能清楚描述需求。

请依次了解：
1. 谁会使用这个功能？
2. 在什么情境下会使用？
3. 用户要完成的具体任务是什么？
4. 现在是谁、怎样完成这项任务？
5. 最近发生过什么具体例子？当时输入了什么，人工做了哪些事情？
6. 哪个环节最花时间、最容易出错或最令人不满意？
7. 这件事多久发生一次，每次大约花多少时间？
8. 解决后希望改善什么：速度、准确率、完成率、用户体验，还是减少重复劳动？
9. 哪些事情明确不属于第一版范围？

不要一次把所有问题抛给我。根据我的回答继续追问关键缺口。结束时给我一份简明需求摘要，并保存为 docs/requirements.md。文档中请标记：
- 已由我确认的事实；
- 仍待确认的问题；
- 你的建议；
不要把建议写成已确认事实。

需求摘要应该包含

• 项目名称或临时名称；
• 使用者；
• 触发场景；
• 用户要完成的任务；
• 当前人工做法；
• 当前痛点；
• 预期业务价值；
• 第一版范围；
• 第一版明确不做的事情；
• 尚待确认的问题。

进入下一阶段的条件

至少能用一句话描述：

当【场景】发生时，帮助【使用者】完成【任务】，目标是改善【可衡量的结果】。

如果仍然只有“做个 AI 助手”“做个 Agent 平台”这种宽泛描述，继续访谈，不要进入开发。

第三阶段：和 Codex 画出工作流程卡

目标

还原人现在怎样完成任务。流程卡是判断 Tool、Workflow 和 Agent 的重要依据。

发给 Codex 的提示词

请基于目前确认的需求，进入工作流程梳理阶段。先不要设计 Agent，也不要写代码。

请用通俗的问题带我逐步还原：一个真实的人现在怎样完成这项工作。每轮最多问 1 到 3 个问题。

请查明：
1. 什么事件触发任务？
2. 一开始有哪些输入？
3. 操作者先看什么信息？
4. 接着分别做哪些动作？
5. 每一步依据什么判断？
6. 哪些情况下会走不同分支？
7. 哪些情况下需要追问用户或同事？
8. 哪些情况下需要查询文件、网页、数据库或第三方系统？
9. 哪些动作会改变外部状态，例如发送消息、修改订单、创建记录？
10. 什么条件代表任务已经完成？
11. 哪些情况必须停止并转交人工？

信息足够后，请生成一张工作流程卡，保存为 docs/workflow-card.md。用表格呈现：

| 顺序 | 人工动作 | 所需输入 | 判断依据 | 结果 | 固定或变化 | 是否有副作用 |
|---|---|---|---|---|---|---|

另外列出：
- 固定步骤；
- 可选分支；
- 需要补充信息的环节；
- 需要查外部资料或系统的环节；
- 需要人工判断或授权的环节；
- 结束条件；
- 失败和转人工条件。

请把尚未确认的步骤标为“待确认”，不要自行补齐。

工作流程卡示例

任务：回答顾客的商品尺码问题
触发：用户发送尺码咨询
输入：用户消息、当前商品 ID、用户可能提供的身体数据
步骤：
1. 确认商品
2. 查询该商品的官方尺码表
3. 判断用户提供的信息是否足够
4. 不足时提出必要追问
5. 足够时根据资料起草建议
6. 涉及退款或保证时转人工
完成：回答有资料依据，或说明缺少信息并追问，或已转人工

进入下一阶段的条件

• 你能看懂流程卡，并确认它大致还原了真实工作；
• 不清楚的步骤明确标为待确认；
• 已识别会改变外部状态的动作；
• 已列出什么时候任务算完成。

如果实际操作不是这样，告诉 Codex 哪一步不对，让它更新工作流程卡。

第四阶段：让 Codex 判断普通程序、Tool、Workflow 还是 Agent

先理解四种方案

• **普通程序：**按明确规则完成固定任务，例如检查字段、计算金额、转换文件格式。
• **Tool：**一个可被人或其他系统调用的单一能力，例如查询订单、搜索文档、生成图片。Tool 本身不一定规划多步任务。
• **Workflow：**由开发者提前安排好的步骤、顺序和分支。可以调用模型、Tool 或 Agent。
• **Agent：**目标由人给定，系统会根据上下文和工具结果，在运行中选择下一步、调用工具、追问、检查结果或停止。

发给 Codex 的判断提示词

请根据 docs/requirements.md 和 docs/workflow-card.md，逐个流程环节判断应该用普通程序、Tool、Workflow、模型节点、Agent，还是人工。

先不要写代码，也不要因为我对 Agent 感兴趣就强行得出需要 Agent 的结论。

每个环节请检查：
1. 输入和输出是否清楚？
2. 规则能否提前写清楚？
3. 每次是否按相同顺序执行？
4. 是否必须根据刚得到的结果决定下一步？
5. 是否需要动态选择不同工具？
6. 是否需要主动判断还缺什么信息并追问？
7. 结果能否自动或人工验证？
8. 出错后是否可以撤销或交给人？

使用以下判断规则：
- 固定规则和固定动作：普通程序。
- 一项可独立调用的能力：Tool。
- 流程和分支预先可定义：Workflow。
- 需要理解语言但后续流程固定：Workflow 中加入模型节点。
- 仅某个环节需要根据上下文动态选择工具或追问：该环节使用受限 Agent，其他部分仍由 Workflow 控制。
- 多个环节确实需要动态规划，且有验收方法和安全兜底：才考虑 Agent 主导。
- 高风险且不可复核、不可撤销的动作：先由人处理，不交给自动 Agent。

请生成 docs/solution-decision.md，包含：
1. 总体建议：普通程序、Tool、Workflow、局部 Agent 或 Agent 主导系统；
2. 逐环节判断表：

| 流程环节 | 推荐实现 | 是否需要 Agent | 判断依据 | 风险和限制 |
|---|---|---|---|---|

3. 如果使用 Agent：明确 Agent 负责什么，不负责什么；
4. 如果不使用 Agent：解释 Workflow 或 Tool 如何满足需求；
5. 仍待确认的问题；
6. 可能推翻当前判断的新证据。

结论必须基于流程卡，不要只根据术语判断。

判断原则

• 一项能力被调用，不等于 Agent。它可能只是 Tool。
• 固定的多步骤流程通常是 Workflow。
• Workflow 可以调用 Agent，Agent 也可以调用多个 Tool。
• Agent 不一定要自主完成所有事，可以只负责一个动态判断节点。
• 常见组合是：Workflow 负责主流程，局部 Agent 负责选择和追问，Tool 提供动作，人工负责授权。

第五阶段：生成开发前最基础的项目文件

目标

先让 Codex 创建可维护的项目说明和工作资料，再开始实现。不要一上来生成一堆空文件。

推荐的第一版目录

project/
├── README.md
├── docs/
│   ├── requirements.md
│   ├── workflow-card.md
│   ├── solution-decision.md
│   ├── agent-design.md
│   ├── tools.md
│   ├── test-plan.md
│   └── decision-log.md
├── prompts/
│   └── system-prompt.md
├── tests/
│   └── eval-cases.jsonl
├── src/
└── .env.example

不是每个项目都必须有全部文件：

• 不需要 Agent，就不必建 agent-design.md。
• 没有可调用工具，就不必建 tools.md。
• 还没确定提示词，就先不建 prompts/system-prompt.md。
• 没有 API 密钥或外部配置，暂时不需要 .env.example。
• 简单原型可以合并短文档，但需求、工作流程、方案判断和测试计划要保留。

文件分别记录什么

• **README.md：**项目做什么、给谁用、如何运行配置和测试、当前限制。
• **docs/requirements.md：**使用者、触发场景、痛点、目标、成功标准、范围和不做什么。
• **docs/workflow-card.md：**人工步骤、判断依据、输入输出、分支、副作用、人工接管和完成条件。
• **docs/solution-decision.md：**选择普通程序、Tool、Workflow、局部 Agent 或 Agent 系统的理由。
• **docs/agent-design.md：**仅在需要 Agent 时创建，说明目标、上下文、权限、边界、工具选择、停止和失败处理。
• **docs/tools.md：**工具用途、输入、输出、权限、副作用、错误情况、超时与确认要求。
• **prompts/system-prompt.md：**提示词、版本日期、适用任务、预期输入输出。提示词不能代替程序权限控制。
• **docs/test-plan.md：**测试范围、方式、通过门槛、风险案例和上线前检查。
• **tests/eval-cases.jsonl：**逐条记录测试输入、预期行为、工具、禁做事项和结果。初期也可用 Markdown 表格。
• **docs/decision-log.md：**重要决定、日期、理由、其他选项和重新评估条件。
• **.env.example：**只列环境变量名字和占位示例，不放真实密钥。

发给 Codex 的文件生成提示词

现在根据已经确认的需求、工作流程卡和方案判断，为本项目创建必要的基础文件。

先检查现有项目结构和已有文件。不要覆盖或删除与本任务无关的内容。不要创建大量没有实际内容的空文件。

请根据 solution-decision.md 决定哪些文件确实需要：
- README.md
- docs/requirements.md
- docs/workflow-card.md
- docs/solution-decision.md
- docs/agent-design.md（只有确认需要 Agent 时）
- docs/tools.md（只有存在工具时）
- prompts/system-prompt.md（使用大模型时）
- docs/test-plan.md
- tests/eval-cases.jsonl 或一份可维护的 Markdown 测试表
- docs/decision-log.md
- .env.example（只有需要环境配置时）

要求：
1. 文件内容必须来自已经确认的信息。
2. 未知项标为“待确认”，不要编造。
3. 标出确认事实、建议和假设。
4. 在 docs/solution-decision.md 里说明为什么需要或不需要 Agent。
5. 测试文件至少包含正常输入、缺信息、异常/工具失败、越权或转人工案例；缺少真实案例时明确标成示例。
6. 不要在 .env.example 或源码里写真实密钥。
7. 完成后列出新建和修改的文件，说明用途，并告诉我下一步开发前还需要确认什么。

第六阶段：让 Codex 开始开发，但按小步骤进行

不要一次要求“把整个 Agent 做完”。一个阶段做完、检查结果后，再继续。

开发前检查提示词

请先阅读 README.md 和 docs/ 中的需求、流程、架构与测试文件，检查当前代码结构。

此时先不要改代码。请告诉我：
1. 现有项目技术栈和入口在哪里；
2. 本次需求涉及哪些模块；
3. 需求文档与现有代码有没有冲突；
4. 有哪些关键假设仍待确认；
5. 你建议把工作拆成哪些小步骤；
6. 每一步如何验证结果。

如发现文档互相冲突，请先指出并提出需要我确认的问题，不要自行选一个版本。

开发步骤 A：实现 Workflow 外壳和确定性逻辑

请按照已确认的 docs/solution-decision.md，先实现确定性的基础流程和 Workflow 外壳。暂时不要增加未批准的 Agent 自主能力。

要求：
- 按 docs/workflow-card.md 实现固定步骤和分支；
- 将输入校验、权限检查、业务规则放在确定性代码里；
- 失败时返回清楚的状态；
- 保留人工接管点；
- 不改变无关模块；
- 修改前先说明将改哪些文件；
- 完成后说明实现了什么、没有实现什么，以及怎样本地验证。

如果方案是单独 Tool，就把“Workflow 外壳”改为实现已确认的 Tool 接口。

开发步骤 B：实现工具接口

请根据 docs/tools.md 实现本阶段批准的工具接口。

每个工具需要：
- 参数校验；
- 权限检查；
- 明确的返回结构；
- 超时和错误处理；
- 日志中避免记录不必要的敏感信息。

只实现文档列出的工具。不要添加万能工具、额外权限或未确认的外部操作。完成后用成功、无数据、参数错误、无权限和超时等案例验证。

开发步骤 C：只在确实需要的环节加入 Agent

如果方案判断不需要 Agent，就跳过此阶段。

根据 docs/solution-decision.md 和 docs/agent-design.md，只为文档明确指出的环节加入 Agent。

Agent 只能：
- 处理指定的单一目标；
- 使用 docs/tools.md 列出的白名单工具；
- 按已定义的结构返回结果；
- 遵守最大轮数、调用次数和成本限制；
- 在信息不足、无依据、工具失败或超出权限时停止或转人工。

请确保：
1. 工具调用由程序验证和执行，模型不能直接访问任意系统。
2. 关键权限由代码强制执行，不依赖提示词。
3. Agent 不能执行设计文档未批准的副作用动作。
4. 将运行过程记录到适当日志，但避免暴露密钥和不必要的个人信息。
5. 不要扩大 Agent 的职责范围。

完成后说明 Agent 具体负责哪个节点，哪些工作仍由 Workflow、普通代码或人工负责。

开发步骤 D：补充界面或调用入口

请基于当前已经实现并确认的后端能力，接入用户界面或调用入口。

界面需要清楚显示：
- 用户输入；
- 处理状态；
- Agent 或 Workflow 的结果；
- 需要用户补充的信息；
- 转人工或工具失败的原因；
- 如果结果需要确认，应提供明确的人工确认动作。

不要在前端暴露 API 密钥。不要为了展示 Agent 思考而泄露系统提示词、密钥或敏感数据。完成后按现有项目方式运行和检查。

每个开发步骤结束都要求 Codex说明

• 改了哪些文件；
• 为什么改；
• 实际行为如何；
• 做了哪些验证；
• 哪些验证通过、哪些未通过；
• 是否需要更新需求、流程、工具或测试文档；
• 当前有哪些风险或未完成事项。

第七阶段：测试、验收和迭代

测试提示词

请根据 docs/test-plan.md 和 tests/ 中的案例测试当前实现。不要为了让测试通过而随意修改预期结果。

至少检查：
1. 正常输入；
2. 缺少必要信息；
3. 模糊或多义输入；
4. 工具返回空结果；
5. 工具失败或超时；
6. 不允许的工具或参数；
7. 必须转人工的情况；
8. 结构化输出格式是否正确；
9. 最大轮数和停止条件；
10. 有没有超出文档范围的外部副作用。

请报告：
- 每个案例的预期与实际结果；
- 通过和失败数量；
- 失败原因；
- 是否存在高风险问题；
- 建议修改哪些实现或文档。

在确认失败原因前，不要直接大范围改代码。

根据失败案例修复

针对刚才确认的失败，请先说明根因，并指出相关文件和代码路径。然后提出最小修复方案，说明可能影响的现有行为。

修复后重跑相关案例和必要的回归测试，并同步更新测试记录和文档。没有实际执行的测试必须标记为未运行，不要说成已通过。

上线前检查提示词

请依据需求、架构和测试文档，对当前版本做上线前检查。不要只检查程序能否启动，还要检查行为是否符合范围。

检查：
- 功能是否满足已确认的成功标准；
- 是否实现了文档明确排除的行为；
- Agent 是否只能调用白名单工具；
- 权限和高风险操作是否由程序检查；
- 工具失败时是否安全停止；
- 是否有超时、最大轮数和成本限制；
- 是否泄露密钥或敏感信息；
- 是否可以人工接管；
- 日志是否足以排查问题；
- 测试案例是否覆盖失败和越权情形。

请给出“可进入小范围试用 / 仍需修复 / 暂不适合试用”的结论，并逐项说明证据。没有执行的检查必须标为未执行。

小范围试用建议

1. 只处理一个明确任务；
2. 先让 Agent 生成草稿，不直接对外发送；
3. 先开放只读工具；
4. 让熟悉业务的人抽查结果；
5. 记录错误、追问、人工接管、耗时和费用；
6. 修复资料和流程问题后，再考虑开放更大权限。

与 Codex 协作的实用习惯

1. 让 Codex先复述，再做修改

请先用自己的话复述你理解的目标、范围和限制，并列出你准备修改的文件。确认需求后再改。

2. 要求测试证据

请告诉我具体运行了什么命令或测试，实际输出是什么。没有运行的测试请标为未运行，不要说通过。

3. 保持文档和代码同步

需求、流程或权限改变后，让 Codex同步更新 requirements.md、workflow-card.md、solution-decision.md、agent-design.md、tools.md、测试计划和 README.md。

4. 一次只改变一个主要因素

如果同时改提示词、模型、工具和流程，出问题后就很难判断原因。一次先改一个主要因素，再重跑同一测试集。

5. 把“不确定”保留在文档里

未确认的接口、数据权限、业务政策和目标指标应标为待确认。不要为了让方案看起来完整而自行补全。

完整流程速查

阶段	你和 Codex 做什么	主要产物
1. 说明目标	告诉 Codex你是初学者，先访谈不写代码	初步方向
2. 需求访谈	确认使用者、问题、现状、价值和范围	docs/requirements.md
3. 流程还原	记录人工操作、判断、分支和结束条件	docs/workflow-card.md
4. 方案判断	判定普通程序、Tool、Workflow、Agent 或人工	docs/solution-decision.md
5. 准备基础文件	只创建当前确实需要的文档和测试文件	README、docs、tests
6. 分阶段开发	先确定性逻辑，再工具，再局部 Agent 和界面	可运行的 MVP
7. 测试迭代	测正常、异常、权限和人工接管	验收结果和迭代记录

**核心判断：**Tool 是一个能力；Workflow 是提前编排好的流程；Agent 是运行时根据结果决定下一步的部分。一个成熟系统通常会把它们组合起来。如果 Agent 没有带来可验证的收益，就不要为了“做 Agent”而添加它。

从一个真实的小任务开始，先和 Codex确认流程、方案、边界和验收标准，再逐步开发。