AI Agent三層架構：多數內容只講了第一層

过去两年我读了很多关于 Agent 架构的文章，几乎全部集中在同一层：Agent 如何思考。Prompt chaining、routing、orchestrator-workers、evaluator-optimizer、ReAct、plan-and-execute。这一层的内容已经相当丰富，我不打算再添砖加瓦。

真正让我一直感到不安的是另一个问题。我见过的、审查过的事故，没有一起是因为选错了编排模式。它们都来自一个 Agent 做了没人决定它可以做某件事。

一个对订单数据库只有读权限的客服 Agent，因为客户写了"我被重复收费了，帮我处理一下"，就从 SELECT 升级到 DELETE。一个外包 Agent 向政策问答机器人询问高管遣散费问题，从一份它根本没有权限访问的文档中得到了正确、有据可查的答案。一个应付账款 Agent 支付了一张 4200 美元的发票，在 pod eviction 中途被杀死，重试时又付了一遍。

这些都不是推理失败。在每一个案例中模型做的事都是可以辩护的。它们是架构失败，而且都发生在框架之下的两层。

AI Agent 有三层，大多数内容只覆盖了第一层：

Agent = Model + Harness。模型提议；Harness 处置。工具调用是一个请求，不是动作，让这个请求安全地执行的一切都在模型之外。这个系列是关于这两层的 18 个模式，每个模式都有可运行的代码作为支撑，并将它所预防的失败做成了一个可以执行的程序。

代码在 github.com/shashikanth-gs/agent-harness-patterns——314 个测试，无需 API 密钥即可离线运行。

框架层不是问题所在

我要明确声明我没有主张什么，因为"框架不重要"这种话会被抽离语境地引用。

框架层已经有充分的覆盖，你应该去读那些内容。Anthropic 的 Building Effective Agents 是关于工作流模式最好的短篇 treatment——prompt chaining、routing、parallelisation、orchestrator-workers、evaluator-optimizer——其核心建议（"使用最简单的方案，加持 Agent 行为只在它有回报时才加"）是正确的，但被广泛忽视。Antonio Gulli 的 Agentic Design Patterns 汇总了 21 个模式，有 LangChain、CrewAI 和 Google ADK 的可运行代码。在这两者之间，这一层已经有了经典文献。

我的主张更窄，也我认为更难反驳：你在 LangGraph 和 CrewAI 之间的选择不会决定你是否会有事故。你的答案是"谁决定这个 Agent 可以退款，以及什么阻止它退一个不该退的款？"才会。

我验证过这个主张，而不是仅仅断言它。这个系列中的每个模式都写成纯 Python hook，然后不做任何修改地挂载到 LangGraph 和 Microsoft Agent Framework 上，测试断言拒绝消息逐字节完全一致，因为它们来自同一份代码。这在 adapters 文章中有详细说明。模式是可以移植的。框架只是管道。

Harness 实际上是什么

LLM 是一个推理引擎。它读取文本并生成文本，包括文本说"用这些参数调用 issue_refund"。它不能执行任何东西。从这个提议到退款真正到达客户卡上之间的一切，都是 Harness：

 user goal ──▶ ┌────────────────────── HARNESS ──────────────────────┐
               │                                                     │
               │   before_model ─▶ ┌───────┐ ─▶ after_model          │
               │                   │ MODEL │                         │
               │                   └───────┘                         │
               │                       │ tool call (a request!)      │
               │                       ▼                             │
               │   before_tool ──▶ allow / deny / pause              │
               │                       │                             │
               │                       ▼                             │
               │   execute ──▶ after_tool ──▶ result back to model   │
               │                                                     │
               │   on_event ◀── every step, narrated                 │
               └─────────────────────────────────────────────────────┘

这五个接缝（seam）就是全部架构。这个系列中的每个模式都挂载在其中一个或两个上：

这些不是我的发明。它们是生产级框架已经在不同名称下暴露的东西：Microsoft Agent Framework 称之为 middleware，LangGraph 暴露了 node wrappers 和 interrupt，Claude Code 称之为 hooks。如果你的 Harness 有这些接缝，这里的每个模式都可以移植到它上面。如果没有，那就是一个发现。

五条设计规则，覆盖了大部分工作

这些来自构建全部 18 个模式的实践，它们比任何单个模式都重要：

**工具调用是请求，不是动作。**模型从不执行任何东西。如果你的框架的 tool decorator 直接调用函数，你没有一个治理边界——你只有一个愿望。

**Fail closed。**未注册的工具、缺失的策略、未知的 token、耗尽的预算：全部归结为拒绝。注册不等于授权。

**拒绝必须对模型可见。**一个被拒绝的调用返回 DENIED by policy: <reason> 作为工具结果，这样 Agent 就会重新规划——升级到人工、尝试允许的路径，或如实报告。静默拒绝会产生一个卡住或幻觉成功的 Agent。

**策略在代码中，不在 Prompt 里。**系统 Prompt 中的"你绝不能修改客户数据"只是建议。承受压力的模型会忽略它，遭受 Prompt 注入的模型被指示忽略它。确定性检查是无法被争辩的。

**最严格的胜出，顺序关乎成本，不关乎安全。**当多个控制意见不一致时，DENY 胜过 PAUSE，PAUSE 胜过 ALLOW，与顺序无关。顺序决定你在拒绝之前花费多少，以及错误信息有多好。顺序弄错应该让你得到一个更差的信息，而不是一个漏洞。

Governance——Agent 被允许做什么

Harness——Agent 如何行动

然后是压轴：全部模式在一个 Agent 上组合，以及组合它们时揭示出的缺口。

诚实界定范围

真正的企业 Governance 涵盖 API 管理、网络策略、云 IAM、密钥管理，以及安全运营中心。这些都不适合放在一个仓库里，我也不打算假装可以。 如果有人向你推销"完整的 AI Governance"作为一个库，他们在卖的是一个有自信品牌加持的子集。

这个系列覆盖的是属于 Agent 自身设计的部分——策略与循环交汇的接缝，在代码审查中而不是在 Terraform 中做出的决策。当一个模式需要基础设施才能真正生效时，我会明确说明：sandboxing 文章明确指出 Python 函数不是隔离，容器才是；audit 文章明确指出防篡改只有当链头发布到 Agent 无法到达的地方时才能成为证明。

这个边界是我能提供的最有用的东西。大多数 Agent Governance 内容对此含糊其辞，这就是团队最终相信 regex 就是沙箱的原因。

常见问题

"Agent harness"是真正的术语还是行业黑话？

过去一年它已成为标准术语。Databricks、Fiddler AI 和 Firecrawl 在 2026 年都发布了关于 Agent harnesses 的文章，Microsoft 的 Agent Framework 和 Agent Governance Toolkit 用"middleware"和"Agent OS"的名字实现了这个概念。底层思想——模型周围的运行时是一个有自己关注点的独立架构层——比这个标签更古老。

我需要全部 18 个模式吗？

不需要，在低风险 Agent 上采用全部模式是一个错误。每篇文章的"何时不使用"部分和"何时使用"部分一样长，因为对于只读文档机器人诚实的答案是"你大约需要其中两个"。如果你的 Agent 接触系统 of record，从身份传播和权限代理开始；如果它有无限循环，从成本预算开始。

这会取代我的框架吗？

不会。仓库中的参考 Harness 是为了让模式可以独立阅读和测试——大约 150 行。在生产环境中，你把相同的模式挂载到你已经运行的任何框架上，这就是 adapters 在 LangGraph 和 Microsoft Agent Framework 上演示的内容。

为什么用 OWASP ASI 标识符而不是通用安全语言？

因为"ASI01"是可检查的，而"遵循安全最佳实践"不是。OWASP Agentic Applications 2026 Top 10 经过了一百多名从业者的同行评审，按 ID 引用意味着读者可以验证我关于某个风险的声明是否与标准一致。这是一个值得普遍采用的习惯：优先选择可以被验证的声明。

延伸阅读

OWASP GenAI Security Project, Top 10 for Agentic Applications 2026 — ASI01–ASI10

Anthropic, Building Effective Agents

Microsoft, Agent Framework overview and the Agent Governance Toolkit

OpenAI, A Practical Guide to Building Agents

Antonio Gulli, Agentic Design Patterns — 这个系列故意不重复的框架层目录

本系列下一篇

下一篇：confused deputy——企业 Agent 部署中最常见的架构缺陷，也是整个构建过程中看起来像好工程的那种。