Agent 设计原则

Agent 领域不缺 demo，缺的是能稳定跑在生产环境里的系统。好消息是：2024 年底到 2026 年这两年多里，Anthropic、Princeton（SWE-agent 团队）、OpenAI 以及一批独立实践者把各自踩过的坑公开了出来，这些经验高度收敛——收敛到几乎可以用八条原则概括。

这一页把八条原则逐条拆开：出处是什么、什么样的设计算遵守（正例）、什么样的算违反（反例）、以及一份可以直接拿去 code review 的检查项。它们不是并列的八条建议，而是有内在顺序的：先决定要不要做（原则一），再决定怎么做接口（二、五），然后让它跑得稳（三、四、六），最后让它持续变好（七、八）。

在动手之前建议先读一遍 Agent 全景解剖 和 Agent Loop，下面的讨论默认你已经知道一个 agent 的基本运行结构。

一、简单优先：能 workflow 不 agent，能单 agent 不多 agent

出处

这条原则的权威表述来自 Anthropic 2024 年 12 月的文章 Building Effective Agents，原文是：

When building applications with LLMs, we recommend finding the simplest solution possible, and only increasing complexity when needed. This might mean not building agentic systems at all.

同一篇文章还给出了至今仍是业界标准答案的区分：workflow 是「LLM 和工具被预定义代码路径编排」的系统，agent 是「LLM 动态指挥自己的流程和工具调用」的系统。Anthropic 观察了大量客户项目后的结论是：最成功的实现几乎都不是复杂框架搭出来的，而是简单、可组合的模式拼出来的；很多应用把单次 LLM 调用加上检索和 few-shot 示例优化好，就已经够了。

正例

• 发票字段抽取：一个 prompt + 结构化输出，连 workflow 都算不上，但准确率达标、成本最低。
• 客服分流：routing workflow——先分类，再进对应的专用 prompt。路径固定，可预测、可测试。
• 代码审查：prompt chaining——先让模型列疑点清单，过一道程序化检查（gate），再逐条展开分析。

反例

• 一个「翻译 + 校对」的需求被拆成 5 个互相对话的 agent，延迟和 token 成本翻了几倍，错误还沿链路传播放大。
• 任务路径完全固定（比如「抓取 → 摘要 → 入库」），却套了带反思循环的自主 agent 框架，调试时连 prompt 都被框架的抽象层挡住了——Anthropic 明确警告过这一点：框架的额外抽象层会掩盖底层 prompt 和响应，让调试变难。

多 agent 是例外不是默认

Anthropic 自己的 multi-agent research system（2025 年 6 月公开的构建复盘）证明多 agent 在「广度优先、可并行」的研究类任务上确实有效，但那是验证了单 agent 上下文撑不住之后的选择，不是起点。多 agent 的代价与适用边界见 多智能体架构。

落地检查项

1. 能否用单次 LLM 调用（加检索/示例）解决？能，就停在这里。
2. 任务路径是否预先可知？是 → workflow；否 → 才考虑 agent。
3. 每增加一层复杂度，能否说清它换来了什么可测量的收益？
4. 如果你在用框架，你是否读得懂它发出去的每一条 prompt？

二、为模型设计接口，不为人

出处

这条原则来自 SWE-agent 论文（SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering，arXiv: 2405.15793，NeurIPS 2024）。作者提出了 ACI（Agent-Computer Interface） 的概念，与为人设计的 HCI 对应。论文的核心发现是：同一个模型，换一个为 LLM 量身设计的接口（LM 友好的命令、格式清晰的反馈），SWE-bench 上的解决率就有数量级意义的提升——界面设计本身就是性能来源。

Anthropic 在 2025 年 9 月的 Writing Effective Tools for Agents — with Agents 里把同一思想落到了工具层面：不要做 API 的薄封装，要做「高杠杆工具」；工具名要无歧义；返回有意义的人类可读上下文而不是一堆裸 ID；输出要控制 token。他们甚至用 agent 自己跑 eval 来迭代工具描述，迭代后任务耗时下降了约 40%（Anthropic multi-agent research system 复盘中报告的同类实践）。

正例

SWE-agent 的编辑命令设计是教科书案例。它没有让模型直接输出 sed 或 diff 补丁（这两种格式模型都容易写错），而是提供了 edit 命令配合行号范围，并约定「同一时刻只能有一个文件处于 open 状态」。反馈信息也经过裁剪： lint 报错只保留相关行，而不是把整个终端输出倒给模型。

反例

• 把内部 REST API 一对一包成工具：list_users + list_events + get_user_by_id…… 模型要完成「给张三安排明天下午的会」需要串 4 个调用，每一步都可能选错。Anthropic 的建议是合并成 schedule_event 这样的高层工具。
• 工具描述写得像给人看的 API 文档（参数名就是全部说明），模型只能靠猜。
• 把 10 万行的日志文件整个塞进工具返回值。

一句话检验标准（Anthropic 原文）：如果一个工程师看着工具名都不能确定该用哪个，模型也不能。 工具设计的完整展开见 工具与 MCP。

落地检查项

1. 每个工具的名字和描述，拿给一个不了解系统的新同事看，他能准确说出使用场景吗？
2. 工具返回的是「模型下一步需要的信息」，还是「数据库里恰好有的东西」？
3. 错误返回是否包含可操作的提示（如「参数 date 需为 ISO 格式，收到 'tomorrow'」），而不是裸 stack trace？
4. 有没有用真实 trace 迭代过工具描述，而不是写完就没动过？

三、让 agent 可观测可解释：动作预告、轨迹透明

出处

Agent 是非确定性系统：同样的输入，两次运行可能走完全不同的路径。没有 trace 的 agent 出了问题只剩一句「不知道它为什么这么干」。Claude Code 等产品把这件事做成了交互层面的默认行为——每个动作执行前先「预告」（我要运行什么命令、改哪个文件），执行后展示结果，整条轨迹可回放。在基础设施层面，OpenTelemetry 的 GenAI semantic conventions（gen_ai.* 命名空间）在 2025-2026 年间已经成为 LLM/Agent 遥测的厂商中立标准：invoke_agent、execute_tool 等 span 类型和 gen_ai.request.model 这类属性，让你的 instrumentation 和观测后端解耦。

正例

• 每次 LLM 调用、每次工具执行都是一个 span，包含输入、输出、token 用量、延迟，整条 trace 可回放。
• 破坏性动作执行前在 UI 上明确预告并等待确认（这与原则六的权限分级配合）。
• 生产环境按 OTel GenAI 规范打 span，换观测平台（Langfuse、LangSmith、自建 Grafana）不需要重写埋点。

反例

• 只在最终回答记一行日志，中间 20 步工具调用是黑盒。
• 把「可观测」理解成「准确率 dashboard」——数字绿灯亮着，答案全是错的。trace 是给你逐条读的，不是只看聚合指标。

每周亲自读 10 条 trace

Hamel Husain 反复强调的「look at your data」在 agent 场景同样成立：聚合指标只能告诉你出事了，只有逐条读轨迹才能告诉你为什么。把「每周读 trace」排进日程，比买任何观测平台都重要。完整的观测体系见 可观测性。

落地检查项

1. 任何一次失败运行，能否在 5 分钟内拉出完整轨迹并定位到出错的那一步？
2. 轨迹里是否同时记录了「模型看到的输入」和「工具实际执行的结果」？
3. 对终端用户，agent 的长时间任务是否有动作预告和进度可见性？
4. token 用量和成本是否按 trace 可归因（哪个环节烧钱）？

四、失败是常态：为恢复而设计

出处

传统软件的正确性假设是「依赖大概率可靠」，agent 的场景正好相反：模型会误解、工具会超时、网页会变、API 会限流。SWE-agent 论文里一个反直觉的发现是：告诉模型「你刚才的命令失败了」比试图阻止它失败更有价值——模型相当擅长从清晰的错误反馈中自我纠正。Anthropic 在工具设计指南里也建议：错误响应要用来「引导」agent 走向更省 token、更正确的行为（比如提示它用分页或过滤）。

正例

# 带恢复策略的工具执行层：重试、降级、求助三级
def execute_with_recovery(tool_call, max_retries=2):
    for attempt in range(max_retries + 1):
        try:
            return run_tool(tool_call)
        except TransientError as e:          # 超时、限流：值得重试
            if attempt < max_retries:
                backoff_sleep(attempt)
                continue
            return tool_error(f"重试 {max_retries} 次后仍失败：{e}。"
                              f"建议换一个工具或缩小请求范围。")
        except PermanentError as e:          # 参数错、权限不足：重试无用
            return tool_error(f"调用被拒绝：{e}。请检查参数后重试，"
                              f"或改用其他方案。")

关键设计：错误不是抛给上层炸掉流程，而是格式化后还给模型，让它自己决定下一步——换参数、换工具、或者承认此路不通。真正的死路（连模型也兜不住，比如目标系统宕机）才升级给人，见 Human-in-the-loop。

反例

• 对 4xx（参数错误）和 5xx（服务故障）用同一套重试策略，参数错了也傻等重试三次。
• 工具失败时返回空字符串，模型以为「查无结果」并据此继续推理——错误被静默吞掉是最坏的一种失败。
• 没有最大步数/预算熔断，agent 在一个走不通的方向上烧掉几百美元 token。

落地检查项

1. 区分了可重试错误与不可重试错误吗？重试有退避和上限吗？
2. 每种工具失败时，返回给模型的信息足以让它采取不同行动吗？
3. 有全局熔断吗（最大步数、最大 token、最大 wall-clock 时间）？
4. 对不可逆操作，失败时能否回滚或至少留下审计记录？
5. 「彻底失败」的路径是否存在——agent 能不能说「我做不到」而不是硬编一个答案？

五、上下文是稀缺资源：每个 token 都要挣得自己的位置

出处

Anthropic 2025 年 9 月的 Effective Context Engineering for AI Agents 开篇即点题：context 是关键但有限的资源。这不只是 context window 装不下的问题——即便装得下，随着上下文变长，模型的注意力和召回质量会下降（所谓 context rot），token 成本也线性上涨。2026 年的现实是：主流旗舰模型都已支持 1M token 级别的窗口，但「能塞进去」和「塞进去还有效」是两回事，定价结构（部分模型对超长输入加价）也在提醒你上下文不是免费的。

正例

• 压缩（compaction）：长任务接近窗口上限时，把早期轨迹总结成结构化笔记，保留关键决策与未决问题。
• 结构化笔记：agent 把「已确认的事实」「试过失败的方案」写到外部文件，需要时再通过工具读回，而不是永远留在 prompt 里。
• 子 agent 隔离：探索性任务（比如「在这 50 个文件里找相关代码」）交给子 agent，主 agent 只收回提炼后的结论——Anthropic 的 multi-agent research system 正是靠这个解决上下文膨胀。
• 工具输出裁剪：默认截断、分页、过滤，把「取多少」的决策交给模型。

反例

• 把整个对话历史 + 全部检索结果无差别拼接进每一轮 prompt。
• 为了「保险起见」在 system prompt 里塞 30 条 edge case 说明，结果模型在简单 case 上也开始犯糊涂——上下文里的每一行都在争夺注意力。

这套方法论值得单独深读，见 上下文工程。

落地检查项

1. 你知道一次典型任务的 token 构成吗（system prompt / 历史 / 工具输出各占多少）？
2. 窗口接近上限时的压缩策略是什么，压缩后任务成功率有没有验证过？
3. 工具返回值有没有截断和分页机制？
4. system prompt 里每条指令，删掉它 eval 会掉吗？不掉就删。

六、自主性匹配风险：权限分级

出处

「给 agent 多大自主权」不该是一个全局开关，而应该按动作的可逆性和爆炸半径分级。Claude Code 的权限模式是业界参考实现：默认模式下读文件自由、写文件需确认；acceptEdits 模式放开编辑；bypassPermissions（社区戏称 YOLO 模式）则几乎全放开，官方明确建议只在隔离环境（容器、无敏感数据的 VM）里用。背后的思想很简单：自主程度要和出错的代价成正比，和环境的隔离程度成正比。

正例

一个三级权限设计：

from enum import Enum

class RiskLevel(Enum):
    READ_ONLY = 0      # 读文件、搜索、查询：直接放行
    REVERSIBLE = 1     # 写文件、改配置：可自动，但记录审计日志
    IRREVERSIBLE = 2   # 发邮件、删数据、调支付：必须人工确认

def authorize(action) -> bool:
    if action.risk == RiskLevel.READ_ONLY:
        return True
    if action.risk == RiskLevel.REVERSIBLE:
        audit_log(action)            # 留痕，事后可回滚
        return True
    return ask_human(action)         # 升级到人，附完整上下文

权限分级只是纵深防御的一层，prompt injection 等针对 agent 的攻击面见 安全。

反例

• 一上来就 --dangerously-skip-permissions 跑在主力开发机上，agent 被恶意网页内容注入后执行了 rm -rf。
• 反过来，所有动作都要人点确认——人不厌其烦开始无脑点「允许」，确认机制形同虚设，还比全自动慢十倍。权限设计的失败有两个方向，过度收紧和过度放开一样常见。

落地检查项

1. 所有工具按风险分级了吗？不可逆操作是否强制人工确认？
2. 高权限模式是否只允许在隔离环境中启用？
3. 审计日志是否独立于 agent（agent 自己改不了自己的操作记录）？
4. 人工确认界面是否展示足够上下文（完整命令、目标文件、影响范围），而不是一句「允许此操作吗」？

七、评测先行：没有 eval 的优化是盲目的

出处

Hamel Husain 的 Your AI Product Needs Evals（2024 年 3 月，迄今仍是 eval 方法论被引用最多的实践指南）核心主张：成功的 LLM 产品团队和不成功的团队，差别不在于用了什么花哨技术，而在于是否建立了从看数据、做错误分析到写 eval 的迭代闭环。先看 100+ 条真实 trace，归纳失败模式，针对最高频的失败写 eval，然后再改 prompt 或架构——顺序不能反。

正例

• 改 prompt 之前，先有一个 50-200 条的评测集（来自真实失败 case），改完跑一遍，用数字说话。
• 错误分析驱动：发现 40% 的失败是「工具参数格式错」，于是先修工具描述（原则二），而不是先换更贵的模型。
• eval 分层：确定性的单元测试（格式、schema）+ LLM-as-judge（质量）+ 端到端任务成功率，各管各的。

反例

• 「我感觉新 prompt 更好了」——凭 vibe 迭代，两周后系统悄悄退化没人发现。
• 只有 benchmark 分数（SWE-bench、AgentBench 之类）没有自己业务的 eval。公开 benchmark 衡量的是模型选型，衡量不了你的系统在你的流量上是否可靠。

完整的 eval 体系搭建见 Agent 评测 和 Evals 实战。

落地检查项

1. 是否有一个随每次重要变更必跑的评测集？它来自真实失败 case 吗？
2. 失败模式有分类统计吗（哪类错误最多）？
3. 换模型、改 prompt、改工具之前，能预估并事后验证影响吗？
4. eval 本身有没有被校验过（LLM judge 的判定抽样人工复核过多少）？

八、随模型演进简化：昨天必须的脚手架可能是今天的累赘

出处

这条原则的根是 Rich Sutton 2019 年的 The Bitter Lesson：70 年 AI 研究最大的教训是，利用计算的通用方法最终总会打败塞入人类知识的手工方法。Claude Code 创造者 Boris Cherny 在访谈中透露，团队工区墙上挂着装裱起来的 The Bitter Lesson，他们的翻译是：永远不要跟模型对赌。你可以写脚手架（scaffolding，模型之外的所有代码）在某个场景提升 10-20%，但下一代模型可能自己就会做这件事，而你的脚手架反而成了限制——LangChain 团队 2025 年也公开复盘过类似经历：为弱模型设计的刚性 agent 结构，在强模型时代成了瓶颈。

工程含义：脚手架是租来的能力，不是资产。每个脚手架组件都应该有「模型变强后就拆掉」的预期。

正例

• 为弱模型写的「强制分步 planning」模板，在推理模型时代撤掉，让模型自己规划——eval 确认不降反升。
• 为防模型写错 diff 格式而设计的复杂编辑协议，随着模型能力提升逐步简化（SWE-agent 团队自己的 mini-SWE-agent 就是把 ACI 砍到极简的实验）。
• 每个脚手架组件都挂在一个 feature flag 后面，换模型时可以逐个关闭并跑 eval 验证。

反例

• 把 2023 年为 GPT-3.5 时代设计的「思维链咒语 + 12 条行为准则」prompt 原封不动用在 2026 年的模型上，系统提示比任务本身还长，模型被过时的指令捆住手脚。
• 脚手架代码没有任何开关和测试，想拆都不知道拆了会怎样。

每次换模型，先问「能删什么」

模型升级的 checklist 第一项不该是「能加什么新能力」，而是「哪些脚手架可以退役」。能删代码的模型升级才是真升级——删完跑一遍原则七的 eval，用数字确认。

落地检查项

1. 每个脚手架组件能一句话说清「它在补模型的哪个短板」吗？
2. 脚手架在 feature flag 或配置后面吗，能快速关掉跑对比 eval 吗？
3. 上次换模型时，删掉过任何东西吗？如果从来没删过，大概率背上了一摞过期包袱。

九、八条原则速查表

#	原则	一句话	出处
1	简单优先	能单次调用不 workflow，能 workflow 不 agent，能单 agent 不多 agent	Anthropic, Building Effective Agents
2	为模型设计接口	工具是高杠杆、无歧义、token 高效的 ACI，不是 API 薄封装	SWE-agent (arXiv: 2405.15793)；Anthropic 工具指南
3	可观测可解释	动作预告、轨迹可回放、span 标准化，每周亲自读 trace	OTel GenAI 规范；Claude Code 等产品实践
4	为恢复而设计	错误格式化还给模型，分级重试，全局熔断，允许说「做不到」	SWE-agent；Anthropic 工具指南
5	上下文稀缺	压缩、笔记、子 agent 隔离、工具输出裁剪	Anthropic, Effective Context Engineering
6	自主性匹配风险	按可逆性分级授权，高权限只在隔离环境	Claude Code 权限模式
7	评测先行	先看数据做错误分析，再写 eval，最后才改系统	Hamel Husain
8	随模型演进简化	脚手架是租来的，换模型先问能删什么	Sutton, The Bitter Lesson；Boris Cherny

八条合起来其实是一句话：把复杂度花在刀刃上，把简单留给模型，把控制权留给自己。 想把这些原则落到一次完整的构建里，可以从 亲手构建你的第一个 Agent 开始，写完再对照 常见陷阱 自查一遍。

参考资料

• Building Effective Agents — Anthropic —— 原则一与全页基调的出处，workflow 与 agent 的标准区分。
• SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering (arXiv: 2405.15793) —— ACI 概念的原始论文，NeurIPS 2024。
• Writing Effective Tools for Agents — with Agents —— Anthropic 的工具设计指南（2025-09），高杠杆工具与 agent 驱动的工具迭代。
• Effective Context Engineering for AI Agents —— 上下文作为有限资源的系统论述（2025-09）。
• How We Built Our Multi-Agent Research System —— 多 agent 何时值得的工程复盘（2025-06）。
• Your AI Product Needs Evals — Hamel Husain —— eval 先行与错误分析方法论的实践指南。
• The Bitter Lesson — Rich Sutton —— 原则八的理论根源（2019-03）。
• OpenTelemetry: Inside the LLM Call — GenAI Observability —— gen_ai.* 语义约定的官方介绍，agent 遥测的厂商中立标准。