Graph Engineering Explained: The Missing Fifth Layer of AI Agent Architecture

图工程详解：AI 智能体架构中缺失的第五层

Every “my agent isn’t working” postmortem starts the same way: someone rewrites the prompt. Adds a constraint. Adds an example. Ships it again. Three iterations later the agent still can’t hold up in production, and the team is quietly out of ideas — because the prompt was never the layer that broke. 每一次关于“我的智能体无法工作”的复盘都以同样的方式开始：有人重写了提示词（Prompt），增加了一个约束，添加了一个示例，然后再次发布。三次迭代后，智能体在生产环境中依然无法稳定运行，团队也束手无策——因为出问题的根本就不是提示词层。

There are five control layers standing between a raw model call and a system you can actually trust with a business outcome: prompt, context, harness, loop, and graph. Most teams staff and instrument only the first one or two. The failures that show up in production — wrong tool called, same mistake retried forever, output routed to the wrong reviewer — live almost entirely in the layers nobody named. 在原始模型调用与真正值得信赖的业务系统之间，存在着五个控制层：提示词（Prompt）、上下文（Context）、工具包（Harness）、循环（Loop）和图（Graph）。大多数团队只关注并配置了前一两层。生产环境中出现的故障——调用了错误的工具、同样的错误无限重试、输出被路由到错误的审核人——几乎全部源于那些无人命名的层级。

Graph engineering is the newest and least understood of the five: it’s the layer that decides which component runs next, when agents work in parallel versus in sequence, and where a human has to sign off before anything expensive or irreversible happens. This piece breaks down all five layers, works through a single production failure end to end, and shows where evals fit as the measurement system running through every one of them. 图工程是这五层中最新且最不被理解的一层：它决定了下一个运行的组件是什么，智能体何时并行工作、何时串行工作，以及在执行任何昂贵或不可逆的操作前，人类在何处进行审批。本文将拆解这五个层级，通过一个生产环境故障的完整案例进行分析，并展示评估（Evals）作为贯穿每一层的度量系统是如何发挥作用的。

The mental model: five rings around the model 思维模型：围绕模型的五个环 MODEL CALL = prompt + context 模型调用 = 提示词 + 上下文 AGENT = model call + harness + loop 智能体 = 模型调用 + 工具包 + 循环 SYSTEM = agents + deterministic steps + humans, connected by a graph 系统 = 智能体 + 确定性步骤 + 人类，由图连接 EVALS = evidence that every layer actually works 评估 = 证明每一层都在正常工作的证据

Prompt and context sit closest to the model. Harness and loop turn a model call into something that can act and recover. Graph turns a collection of agents, functions, and human checkpoints into a coordinated system. None of these layers replace each other — they’re concentric controls, not pipeline stages, and a production agent uses all five simultaneously. The weakest layer sets the ceiling on how reliable the whole thing is, no matter how good the other four are. 提示词和上下文最接近模型。工具包和循环将模型调用转化为能够行动和恢复的实体。图将智能体、函数和人工检查点的集合转化为一个协调的系统。这些层级互不替代——它们是同心圆式的控制，而非流水线阶段，生产环境中的智能体同时使用这五层。无论其他四层做得多好，最薄弱的那一层决定了整个系统的可靠性上限。

Layer	Controls	Fails as
Prompt	Role, goal, constraints, output contract	Ambiguous instructions
Context	What reaches the window: docs, history, tool results	Missing or noisy evidence
Harness	Tools, file/shell access, sandboxing, permissions	Overprivileged or unsafe actions
Loop	Retry policy, validators, stop conditions, escalation	Infinite retries on the same mistake
Graph	Routing, parallelism, recovery paths, human gates	Work reaching the wrong next step

层级	控制内容	故障表现
提示词	角色、目标、约束、输出契约	指令模糊
上下文	进入窗口的内容：文档、历史记录、工具结果	证据缺失或噪声过大
工具包	工具、文件/Shell 访问、沙箱、权限	权限过大或不安全的操作
循环	重试策略、验证器、停止条件、升级机制	对同一错误无限重试
图	路由、并行性、恢复路径、人工关卡	任务流向错误的下一步

A production failure, diagnosed layer by layer 生产故障，逐层诊断 Consider a coding agent built to fix low-risk defects in an internal payments service. The prompt is reasonable: inspect the issue, avoid unrelated changes, run the tests, return a PR summary. On a clean sample repo, it works. On the real repository, it falls apart in four distinct ways: 考虑一个旨在修复内部支付服务中低风险缺陷的编程智能体。其提示词是合理的：检查问题、避免无关更改、运行测试、返回 PR 摘要。在干净的示例仓库中，它运行良好。但在真实仓库中，它在四个方面彻底崩溃：

It misses an architecture decision buried in the docs — a context failure. It runs a shell command with a broader scope than intended — a harness failure. It retries the same failing test without changing its hypothesis — a loop failure. It sends the pull request down the wrong review path — a graph failure. 它遗漏了隐藏在文档中的架构决策——上下文故障。 它运行了一个超出预期范围的 Shell 命令——工具包故障。 它在不改变假设的情况下重复运行同一个失败的测试——循环故障。 它将拉取请求（PR）发送到了错误的审核路径——图故障。

The natural instinct is to ask “how do we improve the prompt?” That’s the wrong question. Only one of these four failures traces back to the instruction layer — and it isn’t the one that caused the damage. Each failure needs a fix in the layer that actually owns it, not a paragraph bolted onto the system prompt. 人们的本能反应是问“我们该如何改进提示词？”这是错误的问题。这四个故障中只有一个可以追溯到指令层——而且它甚至不是造成损害的那个。每个故障都需要在它所属的层级进行修复，而不是在系统提示词后面强行增加一段话。

Layer 1 — Prompt: steers one model call 第一层 — 提示词：引导单次模型调用 Analyze the reported defect and propose the smallest safe fix. Do not change unrelated behavior. Return the root cause, files changed, test evidence, and residual risk. Stop and ask for approval if the fix changes an external contract. 分析报告的缺陷并提出最小的安全修复方案。不要更改无关的行为。返回根本原因、更改的文件、测试证据和残留风险。如果修复更改了外部契约，请停止并请求批准。

The unit being optimized here is a single model interaction. A stronger prompt reduces ambiguity, but it cannot supply a missing design document, restrict a dangerous tool, or decide who reviews the output. In an agent system, the prompt is the steering wheel — not the car. 这里优化的单元是单次模型交互。更强的提示词可以减少歧义，但它无法提供缺失的设计文档、限制危险工具或决定谁来审核输出。在智能体系统中，提示词是方向盘，而不是整辆车。

Layer 2 — Context: what the model can actually see 第二层 — 上下文：模型实际能看到的内容 Ask a model to summarize risk in an 80-page contract. Dumping the whole document into the window and retrieving the liability, indemnification, termination, and data-use clauses (plus the org’s risk policy) produce two very different answers from the same prompt. The instruction didn’t change — the evidence available to answer it did. For the coding agent, the missing architecture decision is a retrieval problem. Rewording the prompt might paper over one test case; fixing context assembly fixes the whole class of failure. 要求模型总结一份 80 页合同中的风险。将整个文档丢进窗口，与检索责任、赔偿、终止和数据使用条款（加上组织的风险政策）相比，同样的提示词会产生两种截然不同的答案。指令没有变，但回答所需的证据变了。对于编程智能体来说，缺失的架构决策是一个检索问题。重写提示词可能掩盖一个测试用例，但修复上下文组装才能解决这一类故障。

Layer 3 — Harness: the runtime envelope 第三层 — 工具包：运行时环境 The harness is everything around the model call: tools, file access, shell access, MCP connections, sandboxing, permissions, timeouts, logging, approval boundaries. The model can decide “I need to run the tests” — the harness decides whether that’s even possible, which commands are allowlisted, which directory is visible, and what gets recorded. MCP standardizes how an agent connects to tools; it does not decide that an agent deserves production write access. Identity, least privilege, and approval policy still belong to the host and its surrounding control plane. This is usually the first layer a security team asks about, and it’s exactly where the broad shell command should have been caught. 工具包是模型调用周围的一切：工具、文件访问、Shell 访问、MCP 连接、沙箱、权限、超时、日志记录、审批边界。模型可以决定“我需要运行测试”，但工具包决定了这是否可行、哪些命令在白名单中、哪个目录可见以及记录什么。MCP 标准化了智能体连接工具的方式，但它并不决定智能体是否拥有生产环境的写入权限。身份验证、最小权限原则和审批策略仍然属于宿主及其周围的控制平面。这通常是安全团队询问的第一层，也正是那个宽泛的 Shell 命令本应被拦截的地方。

Layer 4 — Loop: the retry contract 第四层 — 循环：重试契约 Loop engineering owns the cycle — act, observe, evaluate, adjust, repeat — plus retry policy, validators, completion criteria, budgets, and escalation rules. It’s a distinct concern from the harness: Harness asks: Can the agent execute the test, in which sandbox, with what timeout? Loop asks: Does a failed test trigger another attempt, what has to change before retrying, how many attempts are allowed, and what counts as done? You can have a perfectly sandboxed, fully logged harness and still watch an agent burn its entire budget retrying the identical failed fix. The coding agent’s repeated test failure needed a new-hypothesis requirement and a retry cap — not broader filesystem access. 循环工程负责整个周期——行动、观察、评估、调整、重复——以及重试策略、验证器、完成标准、预算和升级规则。它与工具包是不同的关注点：工具包问的是：智能体能否在哪个沙箱中、以什么超时时间执行测试？循环问的是：失败的测试是否触发另一次尝试，重试前必须改变什么，允许尝试多少次，以及什么算作完成？即使拥有完美沙箱和完整日志的工具包，你仍然可能看着智能体耗尽所有预算去重试同一个失败的修复。编程智能体的重复测试失败需要的是“新假设”要求和重试上限，而不是更广泛的文件系统访问权限。

Layer 5 — Graph: coordinating the system 第五层 — 图：协调系统 Graph Engineering is the operational paradigm for building complex AI agents and multi-agent systems. 图工程是构建复杂 AI 智能体和多智能体系统的操作范式。