> ## Content Index
> Fetch the complete content index at: https://www.hubwiz.com/blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# 构建AI代理的6个常见错误
- URL: https://www.hubwiz.com/blog/top6-mistakes-when-building-ai-agents/
- Published: 2026-04-06T22:57:14.000Z
- Updated: 2026-04-06T22:57:14.000Z
- Description: 六个代理工程错误，它们会静默破坏生产系统，包含真实数据和修复方案
- Author: admin
- Tags: AGENT, #Import 2026-10-14 14:41

那是一个周四的下午，我收到了Slack消息。

我们的支持代理已经在生产环境中运行了六周。响应速度很快，用户似乎很满意，仪表板显示绿色。

**然后我们的一位客户发来邮件：** 代理两周来一直在提供相同的错误退款政策。不是报错。不是崩溃。而是大规模地自信地给出错误信息。

我们追溯到问题出在一个变得臃肿的上下文窗口，模型正在悄悄地将我们三周前添加的更新政策降权。政策在那里。模型忽略了它。每个"成功"响应都是我们没有 catch 到的谎言。

**那一刻让我学到的代理工程知识比任何会议演讲、论文或书籍都多。**

经过多年构建代理，我几乎将每次失败追溯到相同的六个错误。

它们单独看起来很小。在生产中，它们会复合成我刚才描述的那种静默灾难。

这是我从那些失败中构建的诊断框架。

## 0\. AI代理实际上是什么——以及它如何破坏。

![无](https://www.hubwiz.com/blog/content/images/2026/04/1-G-PAUkSxG3wayfSUkku73g.png)

大多数人认为AI代理"只是一个带工具的模型。"不是。

代理是一个循环，模型在其中观察、决定、行动，并**自主推理**。

**问题？大多数生产中的"代理"悄悄跳过后两个部分：**

- 它们不规划。
- 它们不评估。
- 它们只是反应。

那不是代理。那是带随机性的循环。

这篇文章中几乎每个错误都最终来自那个单一误解。

## 错误1：把上下文窗口当作垃圾桶

![无](https://www.hubwiz.com/blog/content/images/2026/04/1-KpDOTrNbRJqTcYQl1Wxc9A.png)

当东西坏了，反射就是添加更多上下文。更多规则。更多历史。更多例子。**推理听起来合理：** 如果模型看到一切，它会表现更好。

**实际发生的事情在"迷失在中间"研究中有记录：**

模型显著更多地关注提示开头和结尾的内容。**埋在密集中间部分的指令被降权。** 这叫做上下文腐烂。

在一个内部测试中，将关键约束从6000令牌提示中的位置3000移动到位置500，在相同查询上 adherence 从61%提高到94%。

**上下文窗口是工作内存，不是硬盘。**

**每个LLM调用应该有一个作用域任务，只有该任务需要的上下文。**

**在每次调用前问：** 这个特定决定绝对最少需要什么？修剪其他一切。将持久化移到你选择性读取的内存层。

**实际规则：** 从单个提示开始。如果它能完成任务，停止。如果它在特定场景下失败，添加一个针对性步骤。不要分成数十个提示，因为那会产生更多LLM调用、更高延迟和更难的调试。上下文工程是深思熟虑的选择，不是积累。

> ***可推文：*** "上下文窗口不是存储。你添加的每一字节都在与你最重要的指令竞争。"

## 错误2：在赢得复杂性之前构建架构

![无](https://www.hubwiz.com/blog/content/images/2026/04/1-uaTlRy7JPAKleZYB4LefYA.png)

多代理系统有一种诱人的魅力。OCR管道。混合检索。编排器-工作模式。代理RAG。**感觉像是构建AI的严肃方式。**

**每一层都是隐藏的税。更多依赖、更高的延迟、更高的成本、更难的调试。** 团队花几个月构建基础设施，结果什么也没发布。

**以下是生产案例的实际数据：** 一个团队用缓存增强生成替换了他们的主要工作流的多索引RAG系统（带OCR管道、单独嵌入管道、混合检索和代理循环）。结果：

- 查询延迟：**12.4秒→1.8秒**（减少85%）
- 每月LLM成本：**减少68%**
- P95错误率：从8.2%降至0.9%
- 每次事件的调试时间：从小时缩短到分钟

数据适合现代上下文窗口。他们从不需要这种复杂性。

**从可能工作的最简单解决方案开始。只有当你碰到真正需要它们的墙时才添加层。大多数团队添加复杂性是因为他们读到了它，而不是任务要求。**

> ***可推文：*** "生产级AI不是关于最令人印象深刻的架构。是关于最简单且能可靠发布的架构。"

## 错误3：能用工作流时却用代理

![无](https://www.hubwiz.com/blog/content/images/2026/04/1-x0ePlIBmO-toSfybEnqpPw.jpeg)

这个错误比其他任何都代价更高，而且从内部最难看到。

**工作流**是你在代码中定义的一系列步骤。可预测的输入、可预测的执行、可预测的输出。**代理**根据它发现的内容决定采取哪些步骤。工作流快速、便宜且可调试。代理灵活但昂贵。

**大多数团队将代理架构分配给本质上是工作流任务。** 结构化数据提取、报告生成、文档摘要。这些有已知路径。给它们代理架构意味着为你不需要的自主性付费。在实践中，这意味着：

- 与等效提示链相比，token使用量高3到8倍
- 难以SLA的可变延迟
- 一个系统80%的时间工作，但在关键时刻不可预测地失败

**把它想象成一个带特定决策点的转盘：**

- **工作流**：任务路径在执行开始前已知
- **代理**：路径根据代理发现的内容显著改变

**采用工作流优先方法。只有当系统必须自主规划、探索未知路径或从设计时无法预测的失败中恢复时才引入代理。**

对于垂直代理，将已知结构化模式路由到工作流，将开放性请求路由到代理。让任务决定架构。

## 错误4：像对待可靠文本一样解析LLM输出

![无](https://www.hubwiz.com/blog/content/images/2026/04/1-tM9iZMuyYUQXzb6nI1FLiw.png)

你提示模型获取结构化输出。它返回看起来像结构化的东西。你写了一个解析器。它在预发布环境工作了三周。

**然后有一天，缺少一个逗号。多一个空格。不同的大小写模式。生产崩溃。模型没有改变。输出轻微漂移，非确定性系统会这样做。**

许多团队通过对提示JSON来响应。

比自由形式文本好，但仍不是契约。你仍然会得到缺失的键、错误的类型，以及跨运行改变形状的嵌套字段。来自提供商的模型更新会以你没有测试的方式破坏你的解析器。

**停止将LLM输出当作文本对待。在生成时将其当作有模式 enforced 的数据对待。**

```
from pydantic import BaseModel, Field
from openai import OpenAI

client = OpenAI()
class TicketClassification(BaseModel):
    # Field descriptions become part of the model's schema constraint
    category: str = Field(description="One of: billing, technical, general")
    priority: str = Field(description="One of: high, medium, low")
    summary: str = Field(description="One sentence summary, max 20 words")

response = client.beta.chat.completions.parse(
    model="gpt-4o",
    messages=[{"role": "user", "content": f"Classify this ticket: {ticket_text}"}],
    response_format=TicketClassification,  # constrained generation, not post-hoc parsing
)
# .parsed is already a validated TicketClassification object.
# If the model cannot conform to the schema, it fails here.
# The failure is loud and immediate, not silent and three functions later.
result = response.choices[0].message.parsed

```

`response_format=TicketClassification` 告诉API将生成约束为匹配模式的有效JSON。当模式说它必须是三个特定值之一时，模型不能产生 `"category": "urgent"`。违规在边界处失败，而不是破坏你的数据管道。

值得知道的注意事项：结构化输出增加50到100ms延迟开销。保持模式浅，嵌套少于三级。只有在结构真正需要时才使用这个。如果你需要纯文本，接受字符串。

## 错误5：只是带随机性的循环

![无](https://www.hubwiz.com/blog/content/images/2026/04/1-6iijLB8ASsGUjQOwNQVCWw.jpeg)

图片由作者提供

**一个不断出现的模式：** 给模型工具，让它选一个，将结果反馈，重复。

**乍一看它看起来像代理。不是。**

模型在响应上一次工具调用，而不是朝向目标推进。它没有计划。它没有停止条件。它没有办法评估自己的进度。

**没有嵌入规划，循环会产生不必要的工具调用、无尽循环和浅层推理。**

Token成本没有上限。

在一个生产事件中，一个处理研究查询的代理在超时前做了47次顺序工具调用，每次会话成本4.30美元，而等效有计划的平均6次调用仅0.38美元。

**在任何工具被调用之前，明确地将规划嵌入循环。**

```
PLANNING_PROMPT = """
Before each action, state:
1. Current goal: what are you trying to accomplish?
2. Current progress: what have you confirmed so far?
3. Next action: the single best next step and why.
4. Completion check: do you have enough to answer confidently?
Hard limit: stop at 6 steps regardless of completion status.
If you cannot answer within 6 steps, say so explicitly. Do not fabricate.
"""

```

**停止条件不是可选的，它们不是建议。**

没有在提示中的明确硬限制，模型将继续。博客文章中的通用ReAct模式不是产品。根据你的特定工具、数据和失败模式定制规划结构。客户支持代理和代码审查代理需要不同的规划结构。\*\*

> ***可推文：*** "没有计划的工具调用循环不是代理。是昂贵的随机性。"

## 错误6：没有评估就发布，然后从用户那里发现回归

![无](https://www.hubwiz.com/blog/content/images/2026/04/1-RhSugyuFEz224Z7Pwv7y9Q.jpeg)

图片由作者提供

这个错误有最长的损害尾巴，而且最容易无限期推迟。

你构建功能、手动测试、发布。没有正式指标。没有自动化评估。没有定义的成功标准。每次发布都是赌注。你从用户发邮件而不是你自己的系统发现回归。

**痛苦现实：** AI系统不会坏。它们会衰减。

**提示变更、提供商的模型升级、链中的新工具，任何这些都会导致微妙的行为变化，这些变化 invisible 直到它们在数周内复合。**

没有评估，你无法判断变更改进了还是降解了系统。你用感觉回答"它工作吗？"

**在发布前定义二进制、任务特定的指标。不是"有用性：3.7/5。"那告诉你什么都不是。**

相反："正确工具选择：是/否。""响应匹配基本事实：是/否。""退款政策准确引用：是/否。"二进制指标是可自动化的、跨版本可比较的，以及失败时可操作的。

**发布前构建黄金数据集：** 25到30个有已知正确答案的真实查询，涵盖主要用例和五个已知边缘案例。每次部署前运行。不是为了100%通过率。为了增量：什么改变了，变更是有意的吗，是改进吗？

**持续这样做的团队在数小时而不是数周内 catch 回归。** 平均检测时间的差异通常是生产事件和周二早晨修复之间的区别。

## 隐藏的复合问题

这六个错误都不存在于孤立状态。它们堆叠。

- **臃肿的上下文窗口使模型不一致。**
- **不一致的行为使你的解析器不可预测地失败。**
- **解析器失败意味着你没有干净的数据来评估。**
- **没有评估，你发布了一个回归。回归添加不规则行为。**
- **不规则行为触发"通过添加更多上下文修复"，这使错误1更糟。**

**每个陷在PoC（概念验证）炼狱中的代理系统至少同时有这三个活跃。** 感觉无法解决的原因是你在调试症状，而根本原因不断相互触发。

修复顺序很重要：

1. **首先评估和输出解析**：它们让你看到实际发生了什么
2. **然后上下文和规划**：它们修复行为不稳定性
3. **最后架构**：一旦你理解系统实际需要什么，就简化

按错误的顺序修复意味着你在调优一个你无法测量的系统。

## 没人告诉你的事

大多数AI工程内容专注于让代理更有能力：更好的模型、更聪明的提示、更花哨的架构。

这是生产系统的错误焦点。

能力是简单的部分。模型有能力。困难的是让它周围系统可靠：紧凑的上下文窗口、正确的自主级别、强制输出合约、嵌入规划、持续评估。构建脚手架，上面的大多数生产失败永远不会发生。跳过它，你就在构建演示，不是产品。

> ***"不可预测的AI代理不是智能。是工程糟糕。"***

生产中工作的代理不是那些有最聪明模型的。是那些工程师对上下文、架构、规划、输出处理和测量做出深思熟虑决定的。这六个错误都是工程决策，不是模型限制。

**模型从来不是问题。它从来不是。**

---

原文链接: [6 Mistakes I Learned the Hard Way That Break Every Agentic App in Production](https://pub.towardsai.net/your-ai-agent-didnt-fail-6683ebdb258f?ref=hubwiz.com)

汇智网翻译整理，版权归作者所有，转载需标明出处