AI Agent 架构：规划、记忆、工具调用的工程化

"Agent"这个词被用滥了。它常被等同于"一个会多轮对话的 AI"，但那只是 chatbot。真正的 Agent 差别在一句话：Agent 是一个能自主决定"下一步做什么"的循环系统——它接收目标，自己规划、调用工具、观察结果、修正计划，直到完成任务或主动求助。

把这句话拆开，就是 Agent 架构的四个组件。

一、四大组件

        ┌──────────── 目标 / 任务 ────────────┐
        ▼
   ┌─────────┐   ┌─────────┐   ┌─────────┐
   │  规划   │──▶│  执行   │──▶│ 工具环境│
   └─────────┘   └────┬────┘   └─────────┘
        ▲            │
        │  观察/结果  ▼
   ┌─────────┐   ┌─────────┐
   │  记忆   │◀──│  反思   │
   └─────────┘   └─────────┘

• 规划（Planning）：把模糊目标拆成可执行步骤，决定每一步用什么手段。
• 记忆（Memory）：记住对话上下文（短期）和跨会话的事实/偏好（长期）。
• 工具（Tools）：能调用的能力——搜索、代码执行、数据库、API、文件读写。
• 执行（Execution）：那个驱动"思考→行动→观察"循环的运行时。

二、两种主流范式：ReAct 与 Plan-Execute

ReAct（Reason + Act） 是最朴素也最通用的范式：每一步都让模型做"思考—行动—观察"。它灵活，适合探索性强、步骤不确定的任务。代价是每一步都做规划，token 消耗高、容易跑偏。

Thought: 我需要先查用户最近的订单
Action: query_orders(user_id="u_123", days=30)
Observation: [{id:"o_1", total:299}, ...]
Thought: 接下来统计总额
Action: ...

Plan-Execute（先规划后执行） 先让模型产出一份完整计划，再逐步执行；执行中若发现计划不可行，回到规划层重订。适合步骤相对清晰、可控性要求高的任务（如数据处理管线）。

工程上的经验法则：默认用 ReAct，当任务结构化、步骤多、想降 token 时，叠加一层 Plan。多数生产级 Agent 框架（LangGraph、AutoGen）都是这两种的组合。

三、记忆：短期与长期

短期记忆就是上下文窗口里的对话历史。难点是窗口有限——长任务很快撑爆。三种应对：

1. 滑动窗口 + 摘要：保留最近 N 轮原文，更早的压缩成摘要。
2. 结构化状态：把关键事实抽成 JSON/实体存进变量，不依赖自然语言历史。
3. 检索式记忆（RAG）：把历史存进向量库，每轮按相关性召回。

长期记忆是 Agent"认人"的关键：用户偏好、已确认的事实、过往决策。通常用一个记忆库（向量库 + 结构化表），按 user_id / session_id 隔离，在每轮开始时把相关记忆注入 system prompt。记忆不是越多越好——要有一套写入策略（什么值得记）和遗忘机制（过时/冲突的更新或删除），否则会被噪声淹没。

四、工具调用：function calling 的工程要点

工具是 Agent 影响真实世界的唯一通道，也是最容易出事的地方。

// 一个结构良好的工具定义
const tools = [{
  type: "function",
  function: {
    name: "create_issue",
    description: "Create a GitHub issue. Use when user asks to track a bug or task.",
    parameters: {
      type: "object",
      required: ["title", "repo"],
      properties: {
        repo:   { type: "string", description: "owner/name, e.g. facebook/react" },
        title:  { type: "string" },
        body:   { type: "string" },
        labels: { type: "array", items: { type: "string" } },
      },
    },
  },
}];

要点：

• 描述写给模型看，要讲清"什么情况下用、不用什么替代"。模型选错工具，九成是描述没写好。
• 参数必须有 schema，required 标清楚，枚举值列全。这是模型填参数的唯一依据。
• 危险操作要确认。写操作（删数据、发消息、付款）默认走"人工确认"闸门，别让模型无监督地动生产环境。
• 幂等与超时。工具调用会失败、会重试，尽量设计成幂等；外部调用设超时，别让 Agent 卡死在等一个不回的 API。

五、把 Agent 推向生产

demo 跑通到生产可用，要补三件事：

1. 循环控制。 必须有最大步数、最大 token、最大耗时三道闸。Agent 一旦陷入"调工具→失败→再调"的死循环，没有上限就是烧钱事故。

2. 错误恢复。 工具失败时，把可读的错误信息回灌给模型（"权限不足，需要先登录"），而不是抛异常中断——Agent 往往能自行换条路。对真正的系统错误，要有降级（fallback 到人工或规则）。

3. 可观测性。 每一步的 thought / action / observation 都要落日志（最好是结构化的，能回放整条 trace）。没有 trace 的 Agent 是黑盒，出了问题无从排查。生产 Agent 至少要埋：每步耗时、token 消耗、工具调用成功率、人为干预率。

六、小结

Agent 的难点从来不是"让模型多会说几句话"，而是如何在一个开放循环里保持可控、可恢复、可观测。规划决定方向，记忆提供连续性，工具赋予能力，而执行层那些"上限、重试、trace"才是区分玩具和生产系统的分水岭。

理解了这套骨架，再去用 LangGraph、AutoGen 或自己手撸，都会有的放矢——它们本质上都是这四个组件的不同拼装方式。