Agent定制开发需求怎么写？功能范围、交付物与验收要求

很多 Agent 项目最后闹得不愉快，问题不在模型能力，而在需求文档写得太虚。文档里写着要智能、要自动、要提效，等到验收那天才发现，双方对做完了这三个字的理解完全不一样。一方期待材料传上去直接出终稿，另一方交出来的是一份问题清单，剩下的时间全花在扯皮上。

这类纠纷可以提前挡掉。需求文档里只要把三件事写死，项目就有了对齐的靶子。功能范围决定做什么，交付物决定留下什么，验收要求决定什么算完成。 三件事缺一件，后面就要用返工来补。

从 ThinkingAI 服务全球 1500 家企业、接入产品超 8000 款的实践看，Agent 的价值最终要靠可验证的结果说话。需求文档，就是那份提前把结果写清楚的说明书。

一、写需求之前先回答三个问题

需求文档写不下去，通常不是文笔问题，而是这三件事没定。

1、这个 Agent 到底替谁完成哪段工作

先把 Agent 当成一名数字员工，而不是一个功能模块。写清四件事，谁在用、什么场景用、多久用一次、用完拿到什么。

不要做全能助手，那类需求没有边界，也没法验收。挑一段具体、重复、有明确步骤和判断标准的工作流，比如每周的报表整理、线索初筛、工单分类。创意类、谈判类、没有判断标准的任务，不适合作为第一个定制项目。

2、成功标准写成一句可验证的话

把目标压缩成固定句式，给定什么输入，输出什么结果，达成什么效果。例如，给定每周导出的订单数据文件，输出一份运营周报，包含数据概览、波动分析和三条优化建议，让人在五分钟内完成复盘。

写不出这句话，说明需求还没想清楚。能写成一句话的目标，才有可能被写进验收。

3、哪些环节必须人工确认

把 Agent 的动作分成三类，可自主完成、需人工确认后执行、当前无法实现。改代码、调支付、控制设备、代表企业对外发消息这类不可逆动作，一律放进第二类。

这一步直接决定功能范围怎么画，也决定验收时该盯什么。

二、功能范围怎么写才不扯皮

功能范围的作用是画边界，不是列愿望。写得越具体，后期越省事。

1、先框住输入和输出

输入要写清触发方式，是对话、文件上传、语音还是接口调用。输出要写清形态，是清单、报告、结构化数据还是执行回执。

输入输出定下来，验收就有了可观测的锚点。一个连输出形态都说不清的需求，最后一定会在验收标准上打架。

2、把工具调用与系统对接逐条列清

这是 Agent 与普通对话机器人的分水岭。模型负责想，活由工具干。所以需求文档里要有一张接口清单，写清系统名称、接口能力、调用权限、读写范围和失败处理方式。

企业里常见的情况是，老旧系统没有开放接口。这类依赖必须单列出来，作为项目前置条件，而不是留到开发阶段才发现。

部署形态同样要写进功能范围。数据不能出域的项目，需要明确本地化方案。像 ThinkingAI 的私有化部署，数据存放在企业自己的服务器上，需求文档里就应该把这条写成硬性要求，而不是一句注意数据安全。

3、知识、记忆与数据来源

Agent 答得准不准，多半取决于喂给它的知识。文档里要写清四件事，知识来自哪些系统、更新频率多高、检索精度要求如何、行业术语要不要专门处理。

记忆要分两层写。短期记忆决定它能不能记住本次对话的上下文，长期记忆决定它能不能记住用户偏好和历史处理习惯。同一指标在企业内只能有一处定义，否则不同业务线问同一个问题，会得到不一样的答案。

4、明确写出不做什么

不在本次范围里的能力、数据源和场景，要单独成表。比如只输出问题清单，不自动生成修订稿；只覆盖三个业务系统，不包括财务系统。

写清楚不做什么，和写清楚做什么同样重要。

三、交付物清单怎么列

交付物是判断项目有没有真实推进的凭据，也是付款节点的依据。

1、按阶段切分，每阶段都有可看的结果

不建议把验收压在项目最后。常规做法是切成四个阶段，基础能力搭建、核心功能落地、优化迭代、正式上线，每个阶段都有能演示、能核对的结果。具体节奏怎么排，可以参考 Agent 落地路线图的思路，再结合自身情况调整。

2、每个阶段要交哪些东西

一份完整的交付物清单通常包含这几类。

• 需求说明书与能力边界表，明确做什么和不做什么
• 方案与架构设计，说明模型、工具和数据的组织方式
• 工具与接口清单，含权限范围和失败处理
• 提示词与 Skill 资产，这是可复用的核心部分
• 评测集与测试报告，含测试样本和通过情况
• 部署与运维文档，含环境依赖和故障处理
• 使用手册与培训，含典型场景演示

其中 Skill 资产最容易被忽略。定制的最大风险是每次从头写、用完就扔，项目越滚越大，最后没人接得住。把行业通用的部分沉淀成可复用的 Skill，下一个项目只在真正个性化的地方投入，定制才能从消耗变成资产。ThinkingAI 的 Skills 库就是按这个思路组织的，把沉淀好的能力直接拿去复用。

3、部署、权限与安全相关材料

私有化项目还要额外约定环境清单、账号权限分级、操作日志留存、数据脱敏规则和审计材料。这部分不只是合规要求，也是后期排查问题的依据。安全边界怎么划，可以参考 Agent 安全与治理里的常见做法，再落到自身制度上。

四、验收要求怎么定

这是最容易起争议的一章，因为 Agent 的输出是非确定性的，同一句话问两次，结果可能不一样。

1、用四类指标代替一句效果好

只看接口可用率会漏掉大量问题，接口通着但答案错的 Agent 随处可见。建议从四个维度约定指标。

四个维度回答的问题不一样。成功率回答它做对了吗，延迟回答它够快吗，风险率回答它闯祸了吗，可控性回答出问题时能不能管住。

2、成功率先约定算法

成功率听起来直观，争议却最多。文档里要回答四个问题，什么叫成功、谁来判定、抽多少样本、用哪套评测集。

长程任务还要拆环节验收。一个需要上百步才能完成的任务，即便单步正确率很高，串起来之后的整体成功率也会明显下滑，三五步看不出来，上百步就可能掉到三成多。所以复杂流程要把关键环节单独设卡，而不是只盯最后一步。

3、验收对象别定错

最常见的错位是按想象中的最终成果验收，而不是按合同里的交付物验收。以文档审核场景为例，如果约定交付的是问题清单，验收时就该验这份清单的质量，比如每一条能否点回原文具体位置、存在型问题和缺失型问题是否分开、规则能否按企业制度配置。按想象中的终稿验收，项目从第一天就偏了。

4、把成本口径也写进验收

Agent 的成本波动比传统软件大得多，任务越长、工具越多、重试越多，消耗就越不可控。只盯每百万 Token 单价意义有限，更值得约定的口径是每个成功任务的成本，把所有推理、工具调用、失败重跑和人工接管都算进去。

上线之后还要按同一口径定期复核，用 Agent 运行监控一类的能力把调用关系、耗时和失败原因留存下来，才有横向对比的基础。

五、三个高频争议怎么提前写进文档

有些问题几乎每个 Agent 项目都会遇到，写进文档的成本很低，事后处理的成本很高。

1、需求边做边加

文档里要写明变更流程，谁提、怎么评估影响、工期和费用怎么调整。建议预留一定比例的变更额度，超出部分走正式评审。没有变更机制的文档，最后一定会变成一张不断加长的愿望清单。

2、只在演示环境跑通

要求用真实数据、真实负载和现场演示来确认，而不是看录屏。演示环境与生产环境的差别要写清楚，包括数据规模、并发量和网络条件。能在真实环境下重复跑通的产品，才算工程化完成。

3、上线之后的持续迭代

模型会更新，数据口径会变，业务规则也会调整。所以要把评测集、监控配置和 Skill 资产完整交接，并约定一段运维支持期。否则项目上线之日，就是效果开始下滑之时。

六、常见问题 FAQ

1、Agent 定制开发需求文档一般包含哪些部分

核心是四块，目标与成功标准、功能范围、交付物清单、验收要求。再补上部署形态、权限与安全、变更流程和运维安排。

2、功能范围要写多细

细到能被验收即可。输入输出形态、工具接口、数据来源、权限边界必须写清，界面样式这类细节可以留到设计阶段。

3、验收指标定多少才算合理

没有通用标准，取决于场景。客服类场景更看重成功率，实时交互场景更看重延迟，涉及资金和权限的场景把风险率放在第一位。所有阈值都应该由双方在立项时共同确认。

4、Agent 定制开发大概要多少钱

价格通常分三段，能力与模型调用、增值服务、集成与定制开发。集成部分弹性最大，建议要求对方给出具体接口清单和人天估算，而不是一个总价。

5、自建 Agent 还是直接采购平台

先看有没有必须自建的约束，比如数据不能出域、流程高度特殊。多数企业的常见做法是站在已有平台上做定制，把通用能力交给平台，把个性化部分做成自己的 Skill。ThinkingAI 的企业级 AI Agent 平台支持多 Agent 协作和私有化部署，属于可以优先评估的一类选择。

6、上线后效果变差怎么办

先分层排查。分清是用户需求变了、意图理解偏了、工具调用错了，还是知识口径过期了。有可观测数据和评测集，才做得到快速定位和同口径复核。