2026 生产级 AI Agent 构建指南：从用例到监控的 8 个步骤

原文来源：Prof. Dr. Kay Rottmann — 从用例选择到原型再到评估框架，完整的生产级 AI Agent 构建指南。

本文由 Prof. Dr. Kay Rottmann（HdM Stuttgart 应用 AI 教授，前 Amazon Alexa 高级应用科学家、Bosch AI 中心 AI 经理、Meta 工程经理）撰写，面向软件工程师、技术产品经理和 CTO——那些真正要把 agent 部署到生产环境的人，而不是只跑通一个 Notebook 演示。

Step 1：缩小用例范围

构建 agent 最常见的错误不是技术问题，而是用例定义出了偏差。"帮我做一个自动化销售的 agent"不是用例，是一个愿望。

一个好的 agent 用例需要满足四个条件：

有界输入——只处理一种类型的请求、一种类型的输入文档。
有界输出——要么给出清晰的答案，要么生成明确的报告，要么执行一个确定动作。
2 到 8 个工具——agent 能调用的工具数量控制在 8 个以内。超过这个数字，目前的大模型很难稳定运行。
可衡量的成功标准——至少有一个指标能告诉你 agent 是否正常工作。

一个真实项目的例子："读取工单，检查客户数据库和知识库，给出回复建议和解决方案路径，看不清楚的 case 自动升级给人工处理。"——范围很窄，四个工具，通过解决率和升级率就能衡量。

—— 广告 ——

Step 2：映射工具和数据源

写代码之前，先把 agent 要调用的工具列出来。每个工具需要明确以下信息：

名称和描述（两三句话）——agent 通过这段描述决定什么时候用这个工具。
输入 Schema（JSON Schema）——这是最重要的行为护栏，不要偷懒。
输出格式——输出有多大？agent 拿到的数据长什么样？
延迟和每次调用的成本。
失败模式——工具挂了会返回什么？agent 能理解这个错误信息吗？

在 Rottmann 的项目中，团队总是在写第一行代码前就把这些信息填到一张表里。听起来琐碎，但能省下几天的调试时间。

Step 3：先构建评估集

大多数 agent 项目卡在这一步：评估集总是留到"有时间再做"，结果就是永远没时间。agent 在没有评估的情况下上线，三个月后有人发现模型更新导致回答质量下降了 20%，但没人知道是什么时候开始的。

评估集必须在写 agent 代码之前构建。具体要求：

第一个 sprint 至少 30 个测试用例，生产上线前要达到 100+。
用真实数据——合成数据覆盖不了真正的失败模式。
三类用例：简单 case（应该通过）、困难 case（应该通过但经常失败）、边缘 case（agent 应该拒绝或升级的输入）。
每个 case 必须有明确的成功标准——要么是预期的结构化输出，要么是回答必须满足的属性列表。

对于 agent 还需要轨迹评估：哪些工具被调用了？调用顺序是否正确？agent 走了几步才完成？

Step 4：写最小的 agent 循环

构建 agent 不需要框架。一个完整的 agent 循环可以控制在 100 行 Python 以内。核心逻辑如下：

code

def agent_loop(task: str, tools: dict, max_steps: int = 10):
    messages = [
        {"role": "system", "content": SYSTEM_PROMPT},
        {"role": "user", "content": task},
    ]
 
    for step in range(max_steps):
        response = llm.chat(messages, tools=list(tools.values()))
 
        if response.tool_calls:
            for call in response.tool_calls:
                result = tools[call.name].execute(call.arguments)
                messages.append({"role": "tool", "name": call.name, "content": result})
            continue
 
        return response.content
 
    raise RuntimeError(f"Agent did not finish within {max_steps} steps")

LangGraph、CrewAI、Anthropic Agent SDK 这类框架提供了追踪日志、重试、并行工具调用、子 agent、流式输出等实用功能。但它们不能替代你对循环本身的理解。

建议：第一个 agent 不要用框架。等你真正理解了需要框架的哪些部分，再加入它——否则你引入的只有复杂度，没有价值。

Step 5：精心编写 system prompt

System prompt 是 agent 最重要的配置文件。至少需要包含以下内容：

角色定义——agent 是谁，为谁工作。
目标——一句话清晰说明任务。
可用工具及其使用场景——虽然模型会读工具描述，但 system prompt 里加一段使用指南帮助很大。
策略约束——什么能做、什么不能做。例如："未经人工审批不得向客户发送任何回复。"
不确定性处理——用明确的指令告诉 agent 在不确定时应该升级或询问。
完成信号——例如通过最终回复的特定格式来标记"任务完成"。

System prompt 不是营销文案。要写得精确，每一条都对照评估集检查，并且像代码一样做版本管理。

Step 6：迭代直到评估通过

真正的工程工作从这里开始。典型循环：

跑评估集。
按失败模式分类——到底哪一步出错了？
修复最常见的那类失败。可选方案按优先级排列：收紧工具描述 → 优化 system prompt → 结构化工具输出 → 重新划分工具边界 → 换模型。
再次跑评估。修复是否引入了新的失败？经常发生——这就是为什么要评估。
重复。

不要试图一次性修复所有问题。 每次只改一个变量，否则你永远不知道什么措施起了作用。

Step 7：加入人工审核

2026 年，没有 agent 能绕过人工审核直接上线。问题只是在哪个环节加入人工。三种常见模式：

前置审批：agent 提出动作，人类点击"批准"。适用于低频、高风险的场景（发送消息、下单、签合同）。
采样审查：agent 自主执行，但 10%-20% 的 case 自动送给人工复查。适用于高频例行任务。
置信度路由：agent 输出一个自评置信度，只有低于阈值的 case 走人工。仅当自评机制可以被校准时才能用——而这在实践中很少能做到。慎用。

审核系统要和 agent 一起构建，而不是事后加。否则第一个月就会积压一堆无人审查的 case，永远补不完。

Step 8：持续监控

生产环境中的 agent 至少需要三层监控：

Trace 日志——每次运行的完整记录：输入、工具调用、工具响应、最终输出、延迟、成本。Langfuse 或 Phoenix 等工具可以轻松实现。
在线指标——成功率、升级率、每次运行的平均工具调用次数、每次 case 的平均 token 成本。这些指标应该在仪表盘上实时展示。
漂移检测——每周对比线上指标与上周的差异。任何显著下降都要调查——通常是模型更新或输入数据分布发生了变化。

没有监控，你就不知道 agent 什么时候出问题——而基于 LLM 的系统出问题是常态。

常见错误与应对

从两年多生产级 agent 的交付经验中，五个最常见的坑：

工具太多——超过 8 个模型就不可靠了。如果确实需要更多，用层级化结构把它们分组给子 agent。
工具描述太模糊——"获取客户数据"不是描述。"根据客户 ID 返回主数据和最近 10 条订单，客户不存在时返回 404"才是描述。
无限循环——永远设 max_steps，通常 10 步就够了。如果 agent 经常需要 30 步，用例定义多半太宽。
幻觉工具调用——模型有时会调用一个不存在的工具。代码必须能干净地捕获这种情况，并告诉 agent："工具 X 不存在，可用的有：A、B、C。"
模型更新后忘记重新评估——当你升级模型时——哪怕只是一个更小的版本——必须完整跑一遍评估集。每次都要，没有例外。

什么时候该用框架？

LangGraph、CrewAI、Anthropic Agent SDK、OpenAI Agents SDK 等框架在以下至少一个条件满足时才有价值：

需要子 agent 或多 agent 编排。
需要流式 UI 实时更新 agent 运行状态。
需要内置追踪和可观测性，不想自己从头造。
需要复杂的重试和降级逻辑。
超过两人同时开发 agent，需要统一标准。

对于一个中小企业的第一个生产 agent，答案是几乎一致的：你不需要框架。 框架只有在第二个或第三个 agent 时才开始变得有价值。

常见问题

2026 年哪个模型最适合 agent？ 截至 2026 年 4 月，Claude 4.6（Opus 和 Sonnet）、GPT-5 和 Gemini 2.5 Pro 是 agent 行为最可靠的模型——工具使用、计划调整、跨步骤一致性都表现最好。简单 agent 用 Claude Haiku 4.5 或 GPT-5 Mini 通常就够了。

每次 agent 运行通常调用多少次工具？ 对于定义良好的用例，通常在 3 到 8 次之间。如果 agent 经常需要 15 次以上，说明用例范围太大或工具粒度太细。

如何控制 agent 成本？ 三个杠杆：（1）缓存重复的工具调用，（2）通过摘要压缩早期上下文来限制长度，（3）简单子任务换用更便宜的模型。在 Rottmann 的项目中，生产环境中每次 agent 运行的成本通常在 5 到 30 美分之间。

如何处理数据保护？ 涉及个人数据时：选择欧洲数据驻留的模型（Azure OpenAI EU、Mistral、Aleph Alpha 或自托管开源模型）。在数据进入模型前做去标识化处理。不要记录任何你不被允许记录的信息。