标准 Agent 开发 SOP（从 0 到 1）

还559

530人浏览 · 2026-04-19 13:32:31

还559 · 2026-04-19 13:32:31 发布

1. 文档目的

这份 SOP 不是讲某一个框架怎么用，而是讲：当我要从 0 到 1 做一个 Agent 项目时，完整的工程路径应该怎么走。

今天主流的工程共识已经很明确：不要一上来就做复杂多 Agent 架构，也不要把精力全花在 prompt 细节上。更稳的做法是：先定义任务和成功标准，再做单 Agent 基线，然后逐步补齐工具、上下文、记忆、harness、评测和上线闭环。Anthropic、OpenAI、LangChain 这几条官方路线在这一点上是高度一致的。(anthropic.com, openai.com, docs.langchain.com)

2. SOP 总览

一个标准 Agent 项目，建议按下面 10 个阶段推进：

立项与任务定义
成功标准与评测集设计
最小可用基线设计
工具层设计
Prompt / Context 设计
状态与 Memory 设计
Harness / Runtime 设计
安全、权限与边界设计
联调、评测、观测
上线与迭代优化

最重要的一句话是：

先把任务工程化，再把 Agent 系统化。

第一阶段：立项与任务定义

3. 先判断：这件事到底该不该做成 Agent

不是所有问题都适合 Agent。

如果任务流程固定、步骤清晰、分支很少，那么通常 workflow 就够了；只有当任务存在不确定性、需要动态选择工具、需要基于中间结果继续决策时，Agent 才真正有价值。Anthropic 明确区分了 workflow 与 agent：前者是预定义路径，后者是模型动态决定执行过程；OpenAI 也把 agent 定义为能代表用户独立完成一段工作流的系统。(anthropic.com, openai.com)

3.1 适合做 Agent 的典型任务

需要跨多个系统取信息再决策
需要工具调用与多轮推理交替进行
需要根据中间结果动态调整路径
任务存在弱结构化、不确定性和异常分支
允许一定程度的自主执行，但仍可加人工审批

3.2 不适合做 Agent 的典型任务

固定模板填报
单轮问答且知识边界明确
简单规则引擎就能稳定完成的流程
对延迟、成本极其敏感且收益不明显的场景

4. 输出第一份《任务规格文档》

在任何编码之前，必须先写任务规格文档。没有这一步，后面 prompt、tool、memory、eval 都会飘。

4.1 文档最少要写清楚的内容

# 任务规格文档

## 任务名称
例如：GitHub 仓库分析 Agent

## 用户输入
用户会提供什么？自然语言、链接、文件、表单还是系统事件？

## 目标输出
Agent 最终交付什么？报告、代码变更、摘要、工单、执行动作？

## 可访问系统
GitHub / Notion / 数据库 / 文件系统 / 邮件 / Slack ...

## 禁止行为
哪些动作绝不能做？例如删除数据、直接发邮件、修改生产系统等

## 成功标准
什么叫成功？正确率、完成率、人工审核通过率、时延、成本上限等

## 失败定义
哪些情况算失败？找错资料、误调用工具、越权操作、漏掉关键步骤等

4.2 阶段出口标准

只有当下面问题都回答清楚，才能进入下一阶段：

用户任务边界是否清楚
最终交付物是否明确
可调用系统和权限是否明确
风险边界是否明确
成功标准是否可验证

第二阶段：成功标准与评测集设计

5. 在开发前先做 Eval，而不是最后补 Eval

现代 Agent 工程与早期 prompt engineering 最大的不同之一，就是 评测前置。Anthropic 强调，eval 最重要的作用之一，就是逼团队把“成功到底是什么”说清楚；OpenAI 也建议先通过 traces 和评测来定位工作流问题，而不是只凭直觉改 prompt。(anthropic.com, developers.openai.com)

6. 第一版评测集怎么建

6.1 建议最小规模

20 个代表性正常样例
5 个边界样例
5 个高风险异常样例
5 个对抗样例（提示注入、歧义输入、权限诱导）

6.2 每个样例至少包含

{
"input": "用户输入",
"expected_outcome": "期望结果",
"allowed_tools": ["可调用工具"],
"must_not_do": ["禁止行为"],
"grading_rule": "如何判断通过"
}

6.3 评测指标建议

任务完成率
工具调用正确率
幻觉率
越权率
平均步数
平均延迟
单任务成本
人工介入率

第三阶段：最小可用基线设计

7. 原则：先单 Agent，后多 Agent

OpenAI 的实践建议很明确：很多任务用单 Agent 加少量工具就能做得很好；多 Agent 只有在任务复杂性已经明显超出单 Agent 上限时才值得加。Anthropic 也强调，成功案例往往来自简单、可组合的模式，而不是一开始就堆复杂框架。(openai.com, anthropic.com)

8. 第一版推荐架构

用户输入
→ 单 Agent
→ 3~5 个高质量工具
→ 一个主循环
→ 一个结构化状态对象
→ 一套最小 eval

8.1 不建议第一版就加入的东西

多 Agent 协作
自动长期记忆写入
复杂 planner / critic / router
大而全工具集
过度抽象的框架封装

第四阶段：工具层设计

9. Tool 是 Agent 系统的能力边界

OpenAI 将工具分为三类：data tools、action tools、orchestration tools。对一个标准 Agent 来说，工openai.com, anthropic.com)

10. 工具设计 SOP

10.1 工具拆分原则

一工具一职责
功能边界窄而清晰
名称直接表达动作
参数尽量结构化
返回尽量短、准、可消费

10.2 推荐工具命名风格

search_repo
read_file
query_database
create_ticket
send_for_approval

不要写：

handle_task
general_tool
do_everything

10.3 工具说明模板

Tool Name: read_file

Purpose:
读取指定路径文件的内容，用于代码分析或文档引用。

When to Use:
- 已经知道文件路径
- 需要查看原文
- 需要验证检索结果

When NOT to Use:
- 不知道文件位置时
- 只是想查找关键词时，应优先使用 search 工具

Parameters:
- path: string, 必填，文件路径
- max_chars: int, 可选，返回最大字符数

Returns:
- content: 文件文本
- truncated: 是否截断
- metadata: 文件名、大小、修改时间

Anthropic 特别建议工具定义里包含用途、边界、参数和示例，写法要像给工程师看的 docstring。(anthropic.com)

10.4 工具返回设计原则

Anthropic 强调，好的工具要返回 meaningful context 且 token-efficient。也就是说，工具结果不是越长越好，而是要尽可能让模型下一步更好决策。(anthropic.com)

建议：

返回结构化结果
保留关键信号字段
避免超长原始 JSON
大结果优先摘要 + 引用位置信息
必要时给证据指针，不直接给全文

11. MCP 在 SOP 中的位置

MCP 不是 Agent 的大脑，也不是 tool 本身。它是一个开放协议，用于把 AI 应用连接到外部 systems、tools 和 data sources。MCP server 可以暴露 Resources、Tools、Prompts 三类能力。(modelcontextprotocol.io)

11.1 什么时候用 MCP

你要接多个外部系统
你希望工具接入方式标准化
你不想为每个系统单独写一套 host 接入逻辑
你的宿主程序需要统一发现和调用外部能力

11.2 什么时候先不急着用 MCP

只有 1~2 个简单 API
原型阶段更重视验证任务价值
工具接入复杂度还远没到瓶颈

11.3 结论

MCP 是接入层标准，不是项目起点。
先把任务和工具跑通，再决定是否要用 MCP 标准化接入。

第五阶段：Prompt / Context 设计

12. Prompt 只是上下文的一部分

Anthropic 2025 对这个问题已经讲得很清楚：Context Engineering 是 Prompt Engineering 的自然延伸。 现代 Agent 的问题，已经不只是“prompt 怎么写”，而是“本轮到底anthropic.com)

13. 推荐的上下文分层设计

13.1 恒定层

system prompt↳
角色
目标
安全规则
行为边界

13.2 任务层

当前用户任务
成功标准
当前阶段
特殊限制

13.3 证据层

检索结果
文件片段
数据库记录
工具返回摘要

13.4 运行层

最近几步工具调用
当前状态对象
未完成待办
错误与重试记录

14. Prompt 模板建议

你是一个[角色名称]。

你的目标是：
1. 完成[任务目标]
2. 遵守[规则]
3. 在不确定时优先获取证据，而不是猜测

你可以使用以下工具：
- tool_a: ...
- tool_b: ...

工作原则：
- 先理解任务，再决定是否调用工具
- 每次只做当前最有价值的一步
- 优先返回结构化结果
- 当证据不足时明确说明
- 对高风险操作必须请求确认

当前任务：
{task}

当前状态：
{state}

相关证据：
{evidence}

最近动作：
{recent_actions}

第六阶段：状态与 Memory 设计

15. 第一版不要先做“炫技式长期记忆”

很多新手一听 Agent，就马上想做长期记忆。其实更稳的做法是：先做结构化状态，再做长期记忆。 Anthropic 在 long-running agents 的 harness 文章里明确指出，长期任务最关键的是跨 session 的信息交接，要显式留下进度工件，而不是指望模型自动记住一切。(anthropic.com)

16. 第一版状态对象建议

{
"task_id": "唯一任务ID",
"goal": "当前任务目标",
"stage": "当前阶段",
"completed_steps": [],
"pending_steps": [],
"key_findings": [],
"used_tools": [],
"risk_flags": [],
"last_error": null,
"next_action_hint": null
}

17. Memory 的演进顺序

V1：仅短期状态

只保留当前任务和最近几轮上下文。

V2：任务持久化状态

支持中断恢复和多轮延续。

V3：事实与偏好记忆

保存用户偏好、系统事实、历史决策依据。

V4：长期个性化记忆

加入写入、检索、更新、遗忘和冲突解决策略。

17.1 记忆写入规则建议

只有高价值、未来仍有用的信息才写
区分短期任务状态和长期用户偏好
对可能过期的事实加时间戳
可撤销、可覆盖、可清理

第七阶段：Harness / Runtime 设计

18. Harness 是让 Agent “稳定运行”的壳

Anthropic 对 harness 的定义很实用：它是让模型能作为 agent 行动的系统，负责处理输入、编排工具调用、控制循环并返回结果。对长任务而言，harness 还需要负责状态持久化、上下文压缩、session 交接等。(anthropic.com, anthropic.com)

19. 一个标准 Harness 至少要包含的模块

19.1 主循环控制

任务开始
模型思考
决定是否调工具
执行工具
更新状态
判断终止

19.2 错误处理

工具错误重试
参数校验失败重试
外部 API 超时
模型输出非法结构时兜底

19.3 上下文治理

历史裁剪
中间结果摘要
长任务分阶段 reset
状态对象持久化

19.4 审批与权限

高风险动作人工确认
写操作与读操作分级
审批点记录日志

19.5 终止条件

成功完成
达到最大步数
达到最大成本
连续失败次数过多
需要人工接管

20. 标准主循环伪代码

while not done:
context = build_context(task, state, recent_actions, evidence)
model_output = call_model(context)

if model_output.type == "tool_call":
result = execute_tool(model_output.tool, model_output.args)
state = update_state(state, result)
log_trace(model_output, result)

elif model_output.type == "final_answer":
if validate_answer(model_output):
done = True
else:
state = add_repair_hint(state)

elif model_output.type == "request_approval":
approval = get_human_approval()
state = update_with_approval(state, approval)

if exceeded_limits():
done = True
escalate_to_human()

第八阶段：安全、权限与边界设计

21. 安全不是最后补，而是从工具层就开始设计

OpenAI 的安全指南强调了几件很关键的事情：不要把不可信输入直接混进高权限指令层；尽量让数据流结构化；对高风险操作加入更强限制和更高审批门槛。(developers.openai.com)

22. 权限分层建议

22.1 只读工具

搜索
读取文件
读取数据库
查看文档
拉取仓库内容

22.2 半敏感工具

创建草稿
生成建议
构建候选方案
标记工单待审核

22.3 高风险工具

删除
修改生产配置
发邮件/发消息给外部用户
执行付款/写数据库
合并代码/直接部署

高风险工具必须默认不自动执行，而是要求审批。

23. 安全检查清单

工具是否最小权限
是否区分只读和写操作
是否有审批点
是否有越权防护
是否处理 prompt injection↳
是否结构化输出
是否记录审计日志

第九阶段：联调、评测、观测

24. Trace 优先，改 prompt 次之

OpenAI 的实践指南里非常强调 traces 的价值：工作流级问题往往要先看 trace 才知道错在模型、工具还是编排。(developers.openai.com)

25. 联调顺序建议

25.1 工具单测

先脱离 Agent 独立测试每个工具。

25.2 Prompt / Context 单轮测

验证模型能否在静态输入下做出合理下一步。

25.3 主循环联调

看 agent 是否能正确走完一整个任务。

25.4 异常路径联调

看工具失败、上下文不全、用户歧义时能否安全退化。

25.5 评测回归

每改一次 prompt、tool、context、memory，都跑回归。

26. 观测指标建议

成功率
步数分布
工具调用频次
工具错误率
人工审批触发率
token 消耗
平均耗时
平均成本
风险动作比例
回退到人工处理比例

第十阶段：上线与迭代优化

27. 上线前的最终检查

27.1 产品层

用户输入边界是否清楚
输出是否可消费
错误提示是否友好
是否允许人工接管

27.2 工程层

日志是否完整
状态是否可恢复
工具超时/重试是否合理
成本是否可控

27.3 安全层

高风险动作是否审批
是否有审计日志
是否有权限隔离
是否防注入、防越权

28. 上线后迭代路线

28.1 第一阶段：稳住基础成功率

修正工具说明、上下文污染、终止条件问题。

28.2 第二阶段：优化成本与延迟

减少无效 tool call，压缩工具返回，缩短上下文。

28.3 第三阶段：加 Memory 与长期任务能力

只在真实业务确认有价值时再加。

28.4 第四阶段：必要时再演进为多 Agent

只有单 Agent 已经出现清晰瓶颈，再引入 planner/executor/reviewer 等结构。

29. 标准项目交付物清单

一个标准 Agent 项目，在里程碑结束时，建议至少交付下面这些文档和资产：

1. 任务规格文档
2. 系统架构图
3. 工具清单与工具说明文档
4. Prompt / Context 设计文档
5. 状态对象 / Memory 设计文档
6. Harness 运行设计文档
7. 权限与安全策略文档
8. Eval 数据集
9. Trace 样例集
10. 上线与回滚方案
11. 监控指标说明
12. 已知问题与后续迭代计划