如何构建 AI Agent：生产级架构与代码实战

AI Agent 不是“加了一段超长系统提示词的 LLM”。真正的 Agent 是一个闭环系统：模型可以选择行动、观察结果、更新状态，并持续运行，直到满足明确的停止条件。模型负责判断，外围运行时负责工具、权限、状态恢复和结果验证。

很多 Agent 项目失败，并不是因为模型不会推理，而是因为系统把宽泛的权限、含糊的工具和不可追踪的状态交给了一个具有不确定性的模型，却没有可靠机制判断任务是否真的完成。

本文从工程决策出发，构建一套生产级 Agent 架构，并给出可以运行的 Python 示例。内容最后一次技术核验时间为 2026 年 7 月 16 日。

核心结论

• 路径确定时用固定工作流，只有需要模型动态选择路径时才使用 Agent。
• 把 Agent Loop 当作有预算、有状态、有停止条件的状态机。
• 工具必须单一职责、强类型、最小权限；工具返回值同样是不可信输入。
• 区分运行状态、会话历史和长期记忆，它们的生命周期与隐私风险不同。
• 发送消息、转账、删除和发布等高影响操作必须经过人工审批。
• 不只评估最终文本，还要评估执行轨迹与真实业务结果。
• 默认从单 Agent 开始，只有权限隔离、上下文隔离或并行收益明确时才增加 Agent。

什么是 AI Agent？

Anthropic 对两种系统做了清晰区分：**工作流（Workflow）**由代码预先定义执行路径；Agent则由模型在策略约束内动态决定步骤和工具。二者都可以包含 LLM，但运行风险不同。

只有同时满足以下三个条件，Agent 的复杂度才通常值得：

1. 任务需要多个步骤或工具；
2. 正确步骤无法提前完全确定；
3. 环境能持续反馈可验证的结果。

如果一个任务可以通过单次调用、RAG 加单次调用或固定 DAG 完成，引入 Agent 往往只会增加延迟、成本和故障面。Anthropic 的官方工程建议也是从最简单的方案开始，只有效果收益能够覆盖代价时才增加自主性。

生产级 Agent 架构

可以用一个公式概括：

Agent = 模型 + Harness + 工具 + 运行环境

模型理解目标并选择动作；Harness管理指令、状态迁移、预算、护栏和异常恢复；工具提供边界清晰的能力；运行环境决定进程能够访问哪些文件、网络、凭证和服务。

循环本身并不复杂。真正的工程工作，是为图中的每条边定义 Schema、超时、负责人和失败策略。

1. 目标与策略

先把用户请求翻译为执行契约：

• 预期结果；
• 允许与禁止的动作；
• 数据访问边界；
• 时间与成本预算；
• 必须人工确认的动作；
• 可验证的完成标准。

“解决客户退款问题”过于含糊。更安全的契约是：“读取订单与支付状态，解释退款资格并生成退款草稿；金额超过策略配置的阈值或涉及修改订单时必须审批。”这里的阈值只是示例策略，不是通用业务规则。

提示词不是权限系统。权限必须由应用代码和工具边界强制执行。

2. 上下文与状态

上下文是模型本轮决策可见的信息，状态是运行时维护的权威记录。不要让不断增长的聊天记录同时承担两者。

检索必须服务于下一步决策：只加载必要上下文，保留来源和时间戳，对变化频繁的业务事实进行实时读取。向量数据库适合语义召回，但不能成为余额、权限或订单状态的影子数据源。

3. 工具设计

工具是能力边界，而不是内部 API 的随手封装。好的工具会让正确操作简单，让危险操作困难。

from typing import Literal
from pydantic import BaseModel, Field

class RefundDraft(BaseModel):
    order_id: str = Field(pattern=r"^ord_[a-zA-Z0-9]+$")
    amount_cents: int = Field(gt=0, le=10_000)
    reason: Literal["duplicate", "damaged", "not_received"]

工具应遵循以下规则：

• 一个工具只承担一个明确职责；
• 输入强类型，输出结构化；
• 明确副作用与失败模式；
• 在工具内部执行身份、权限和租户隔离；
• 设置超时、有界重试和幂等键；
• 只返回决策需要的证据，不返回整表数据或无限日志；
• 把工具描述和工具结果都当作不可信数据处理。

MCP 规范对可互操作工具提出了相同的安全原则：用户应理解暴露给模型的能力，并对敏感调用保留控制权。MCP 解决标准化发现和传输，但不会替应用完成业务鉴权。

4. Agent Loop 与停止条件

运行时持续执行四步：

1. 根据目标和状态构建上下文；
2. 请求模型选择工具、输出答案或升级人工；
3. 执行获准动作并记录观察结果；
4. 更新状态并检查停止条件。

每个循环都必须有硬限制：

MAX_TURNS = 12
MAX_TOOL_CALLS = 20
MAX_WALL_SECONDS = 90
MAX_ESTIMATED_COST_USD = 0.50

这些限制只是起始示例。实际值应根据工作负载延迟、供应商价格、重试行为和中断的业务影响推导，并由运行时强制执行，而不能只写在 Prompt 中。

结果已验证、需要用户决策、连续重复且没有进展或预算耗尽时，系统必须停止。“一直重试直到成功”不是生产策略。

5. 护栏与人工审批

护栏需要分层部署：

• 输入层：识别不支持的请求、Prompt Injection 和敏感数据；
• 模型决策层：根据用户和任务动态限制可见工具；
• 工具输入层：校验 Schema、权限和业务规则；
• 工具输出层：清洗不可信内容并限制大小；
• 最终输出层：校验必要字段、引用与合规要求。

发送消息、资金操作、删除数据、发布内容和授予权限等操作必须设置人工审批。审批界面应展示具体动作和参数，而不是笼统询问“是否允许 Agent”。

6. 可观测性与评测

除延迟、错误率、资源和成本外，Agent 还需要记录：

• 模型请求与响应元数据；
• 工具名称和校验后的参数；
• 工具结果、耗时与错误类别；
• 状态迁移与重试原因；
• 审批事件与操作人；
• 最终结果及验证结论。

Trace 不应包含密钥或无限制的客户数据；导出前进行脱敏，并为 Trace 与业务记录分别定义保留周期。

评测集应来自真实且匿名化的任务，覆盖正常案例、歧义请求、工具故障、越权操作、Prompt Injection 和数据缺失。每次修改模型、Prompt、工具 Schema 或编排逻辑都应回归。文本看起来专业并不代表真实操作正确，业务结果验证才是发布门禁。

一个可运行的 Python Agent

下面使用 OpenAI 官方 Agents SDK。它提供 Agent、函数工具、Guardrail、Handoff、Session 和 Trace 等少量核心原语，便于把注意力放在系统边界上。SDK API 和模型默认值会变化，部署前应锁定依赖并核对最新文档；相同设计原则也适用于其他运行时。

python -m venv .venv
source .venv/bin/activate
pip install openai-agents
export OPENAI_API_KEY="your-api-key"

创建 support_agent.py：

import asyncio
from typing import Literal

from agents import Agent, Runner, function_tool
from pydantic import BaseModel


class OrderStatus(BaseModel):
    order_id: str
    status: Literal["processing", "shipped", "delivered"]
    refundable: bool


ORDERS = {
    "ord_1001": OrderStatus(
        order_id="ord_1001",
        status="delivered",
        refundable=True,
    )
}


@function_tool
def get_order_status(order_id: str) -> OrderStatus:
    """查询单个订单的当前状态与退款资格。"""
    if order_id not in ORDERS:
        raise ValueError("Order not found")
    return ORDERS[order_id]


agent = Agent(
    name="订单客服",
    instructions=(
        "帮助用户了解订单状态和退款资格。订单事实必须调用 "
        "get_order_status 查询。禁止声称已经提交退款；当前 Agent "
        "只能解释规则或草拟后续步骤。缺少订单号时先向用户询问。"
    ),
    tools=[get_order_status],
)


async def main() -> None:
    result = await Runner.run(
        agent,
        "订单 ord_1001 还能退款吗？",
        max_turns=6,
    )
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

运行：

python support_agent.py

这个示例刻意保持最小化：工具只读且无副作用，Pydantic 约束结构化结果，指令明确能力边界，max_turns 限制循环，回答必须基于最新工具结果。

内存中的订单查询只是只读演示，刻意省略了身份认证、租户隔离和并发更新。生产工具必须从可信运行时上下文获取已认证主体，并在返回订单数据前向源系统校验订单归属。

如果要支持真实退款，不要直接暴露 issue_refund。应拆成 draft_refund、明确的人工审批节点和幂等的 submit_refund，并在两个工具内部校验登录用户是否拥有该订单。

2026 年如何选择框架

先定义流程、风险和运维要求，再选择运行时。流行度不是架构需求。

LangChain v1 的标准 Agent API 是 create_agent，基于 create_react_agent 的旧教程应视为迁移资料。LangGraph 的重点是持久化、Durable Execution、流式输出和 Human-in-the-loop 等编排能力，而不是隐藏 Prompt 与架构。

单 Agent 还是多 Agent？

默认从一个 Agent 和少量工具开始。只有满足以下条件之一时才增加 Agent：

• 专家能力需要独立权限边界；
• 一个领域的上下文会显著干扰另一个领域；
• 相互独立的任务能带来真实并行收益；
• 不同团队分别拥有并评测不同能力。

常见模式有两种：由 Manager Agent 保持用户交互并把专家 Agent 当作工具调用；或由分诊 Agent 将任务和必要上下文 Handoff 给专家。

避免把连续三个 Prompt 命名为“研究员、分析师、写作者”就称作多 Agent。它增加模型调用次数，却未必增加证据质量、控制力或最终效果。

上线检查清单

• [ ] 已优先评估确定性工作流；
• [ ] 成功、升级和停止条件明确；
• [ ] 每个工具都有窄 Schema 和明确副作用；
• [ ] 权限由代码强制执行，而不只写在 Prompt 中；
• [ ] 外部内容和工具结果按不可信输入处理；
• [ ] 高影响动作需要针对具体参数的人工审批；
• [ ] 重试有界，写操作具备幂等性；
• [ ] 进程故障后可以恢复运行状态；
• [ ] Trace 能连接模型决策、工具调用与业务结果；
• [ ] 敏感数据已脱敏并定义保留周期；
• [ ] 代表性评测集是发布门禁；
• [ ] 已测试回滚或紧急停止机制。

常见问题

AI Agent 和 RAG 有什么区别？

RAG为模型检索上下文；Agent 控制循环并选择行动。Agent 可以把 RAG 当作工具，但只有检索能力的系统并不等于 Agent。

Agent 必须有长期记忆吗？

不需要。很多 Agent 只需当前运行状态和对权威系统的实时读取。只有明确的用户收益足以覆盖隐私、删除、来源追踪和信息过期风险时，才应增加长期记忆。

如何防止 Agent 无限循环？

设置轮次、工具调用、时间和成本上限；识别参数等价的重复调用；要求每次观察都产生可衡量进展；无法验证进展时升级人工。

工具错误应该返回给模型吗？

返回有界且可行动的错误类别，例如 not_found、permission_denied 或 temporary_failure。不要暴露堆栈、密钥或原始基础设施响应，由运行时决定哪些错误可以重试。

什么时候应该使用 MCP？

当工具或上下文资源需要在兼容 Host 之间提供标准接口时，可以使用 MCP。MCP 改善互操作性，但 Host 仍要负责用户同意、Server 信任、鉴权和工具动作的安全展示。

总结

Agent 工程的基本单元不是 Prompt，而是受控反馈循环。生产级 Agent 必须具备有界工具、权威状态、明确停止条件、用户对高影响操作的控制权，以及与真实结果绑定的评测。

先构建能够解决问题的最小循环，确保每个动作可观察、可验证、可恢复，再逐步增加自主性。

一手资料

• Anthropic：Building Effective Agents
• OpenAI Agents SDK 官方文档
• LangGraph 官方概览
• LangChain v1 迁移指南
• Model Context Protocol 规范