Agent软件架构设计原则

来自《深入理解Agent》总结归纳

https://github.com/bojieli/ai-agent-book

在 Agent 系统的工程落地与架构设计中，构建高可靠、高可用、可扩展的智能体系统是一项复杂的系统工程。

一、构建有效 Agent 的三大核心原则

保持简单：从最简单的方案开始，仅在必要时增加复杂度；直接的 API 调用优于复杂的框架。在任务编排上，应遵循“单次 LLM 调用 → 确定性工作流 (Workflow) →单Agent-》多Agent Agent”的演进路径，避免过早用高昂的延迟和 Token 成本换取不必要的系统复杂度。

保持透明：明确展示 Agent 的规划步骤、执行日志和决策轨迹，这既便于调试，也是建立用户信任的前提。

设计好工具接口（ACI）：强调从 Agent 视角设计接口（易于理解与使用），而非程序员视角的传统 API。工具命名与参数要直观，容易误用的地方应通过设计消除错误（即“防呆”原则），避免模糊接口放大系统性错误

二、通用 Harness 原则

约束优先于指导：能用代码/系统强制的规则就不要用自然语言文档或提示词建议（如类型约束、CI 检查优于提示词）。

验证要自动化：依赖测试套件与自动化检查，消除人工审查的扩展瓶颈。

反馈越快、越结构化越好：错误信息越详细且越接近发生时刻，Agent 纠正效率越高（例如通过 Agent 状态栏提供详细上下文信息与计数器）。

回退要可靠：基于沙盒、分支或快照机制，确保试错可逆

三、工具（ACI）设计原则

通用与专用结合：通用基础能力用于组合与探索；涉及支付、删除数据、发送邮件等高风险/强业务约束操作，必须封装为参数明确、权限受限且可审计的专用工具。

结构化返回与分页：搜索类工具应返回结构化候选列表（如标题、摘要），而非全文倾倒；支持分页/游标（cursor）由 Agent 决定是否深入读取。

显式截断与按需读取：文件/数据读取工具应支持 offset/limit；达到截断阈值时必须显式注明省略量与后续读取方法，严禁静默截断造成信息误判。

利用只读优势：感知/只读类工具应积极利用安全缓存与并发执行提升效率。

四、上下文与提示词工程原则

KV Cache 友好的上下文布局设计：静态前缀保持字节级绝对不动将系统提示词和工具定义作为稳定的请求前缀，一旦确定，绝对避免进行动态增改或工具动态信息永远追加到末尾

知识显式化与结构化：将隐式状态（如重试/调用计数、任务阶段）通过“Agent 状态栏”等显式元信息呈现在上下文末尾，强化注意力引导并降低模型重新计算的开销。

上下文按需加载（Skills 机制）：将元数据目录与完整指令分离，目录先于正文呈现，完整指令/正文在被选中后按需注入，优化上下文成本。

明确的上下文压缩保留优先级：压缩时必须完整保留“架构决策与关键约束”、“已修改文件及变更记录”、“验证状态 (pass/fail)”与“未解决的 TODO”，而中间工具输出仅保留结论。

对齐模型厂商训练方法论：交互模式尽量选用基础模型专门训练并推行的范式。

五、评估与持续进化原则

没有评估就没有进步：评估对象是“模型 + Harness”的组合体，需通过系统性实验与消融实验区分模型能力与工程缺陷。

人机交互评估采用渐进式信息透露：模拟真实用户时，不一次性暴露全部需求，而是按需在对话中逐步透露，考验 Agent 主动澄清的能力。

区分机制指标与目标指标：不能把过程改变（机制指标，如计划长短）误当做最终优化目标（目标指标，如会话成本），且必须设立不可跌破的护栏指标。

隐私内置原则：从一开始将隐私与安全约束内嵌于数据采集与评估机制中。

最小更新与可证伪契约：持续进化不盲目堆砌 Prompt，而是基于失败证据提出最小变更提案，通过回归测试、对照实验和灰度验证后合并发布。

六、多 Agent 协作与架构设计原则

以信息增量与 ROI 为决策前提：只有在能引入单个 Agent 无法获得的外部新信息（执行反馈、跨模态视觉、独立校验）且收益覆盖额外 token 成本时才采用多 Agent。

专业化分工与上下文隔离：与其构建全能 Agent，不如构建专精子 Agent；通过结构化的移交包（handoff package）或协议传递信息，避免全局上下文膨胀和思维惯性干扰。

子 Agent 提示词规范：角色定义清晰、明确标注输入来源（防止提示注入）、严格界定任务边界、输出格式标准化。

明确的终止与容错控制：建立动态步骤预算分配、基于事件流的级联终止机制、乐观锁隔离以及人在回路（HITL）超时降级策略。