1. 从Express.js到Agent Express：为什么中间件是构建智能体AI的全部所需

如果你是一名Web开发者，尤其是用过Express.js、Koa或Hono这类Node.js框架，那么恭喜你，你已经掌握了构建现代AI智能体（Agent）最核心的抽象思维。这不是什么未来科技，而是你每天都在写的 (ctx, next) 模式。最近我在给我的AI智能体添加记忆管理功能时，被各种框架里“记忆模块”、“记忆后端”、“检索器链”、“缓冲区窗口”这些新概念搞得头大。在另一个框架里，我需要配置一个嵌套了三层的“处理器”配置对象。盯着满屏的文档标签，我突然意识到：这不就是中间件吗？在模型调用前拦截上下文，修剪旧消息，然后把控制权交给下游。每个Web开发者都写过上百遍这个模式。正是这个顿悟，催生了Agent Express这个项目。它想证明一件事：构建生产级的AI智能体，你真正需要的只是一个你早已熟知的、强大的中间件系统。

2. 核心理念拆解：智能体即中间件栈

2.1 请求-响应循环与模型-工具循环的同构性

我们先来解构一下AI智能体的核心工作流。一个典型的工具调用智能体，其生命周期大致如下：接收用户输入（一个问题或指令），让大语言模型（LLM）思考并决定是否需要调用工具（比如查询天气、搜索网络），如果调用工具，则执行工具获取结果，再将结果返回给模型进行下一步思考，如此循环，直到模型认为可以给出最终答案。这个过程，被称为“模型-工具-模型”循环。

现在，让我们看看一个经典的Web服务器，比如Express.js。它的工作流是：接收一个HTTP请求，经过一系列中间件（如身份验证、日志记录、请求体解析），到达路由处理函数，生成响应，再经过一系列中间件（如响应格式化、错误处理），最终返回给客户端。这个过程，被称为“请求-响应”循环。

你有没有发现它们的结构惊人地相似？都是一个“上下文对象”（在Web中是 req / res ，在智能体中是 ctx ）流经一个函数栈（中间件栈）。栈中的每个函数都可以检查这个上下文、修改它，然后决定是调用 next() 将控制权传递给栈中的下一个函数，还是直接中断流程返回响应。这种“洋葱模型”的抽象能力是极其强大的。

2.2 如何用中间件思维解构智能体功能

一旦接受了这个设定，所有复杂的智能体功能都变得清晰起来：

• 记忆管理 ：这就是一个中间件，它在模型调用前被触发，检查 ctx.history （对话历史），根据某种策略（比如只保留最近10轮对话，或者总结早期对话）来修剪或压缩历史，然后再调用 next() 。它不关心后面是调用模型还是其他什么，只负责处理好历史上下文。
• 预算控制 ：这是一个守卫中间件。在调用 next() （通常是去执行昂贵的模型调用）之前，它先检查 ctx.state 中累计的成本是否已超过预设限额（比如0.5美元）。如果超了，直接抛出一个 BudgetExceededError ，流程中断，模型调用根本不会发生。
• 自动重试 ：这是一个包装中间件。它把对 next() 的调用（即实际的模型调用）包裹在一个循环里。如果调用失败并抛出可重试的错误（如速率限制），它会等待一段时间（通常是指数退避），然后再次尝试调用 next() ，直到成功或达到最大重试次数。
• 链路追踪与日志 ：这是一个观察中间件。它在调用 next() 之前记录开始时间戳，在 next() 解析之后记录结束时间戳、计算耗时，并将这些信息连同请求/响应内容一起记录到 ctx.state 或外部日志系统。

所有这些功能都是独立的、可插拔的模块。它们通过共享的 ctx 对象进行通信，通过调用 next() 来协作，但彼此之间没有直接的依赖关系。你可以像搭积木一样组合它们： app.use(记忆中间件); app.use(预算中间件); app.use(重试中间件) 。这种组合性是软件工程中梦寐以求的特性。

3. Agent Express 架构深度解析

3.1 核心三概念：Agent, Session, Middleware

Agent Express 的API设计极度精简，只围绕三个核心概念构建，这对于降低认知负荷至关重要。

1. Agent（智能体） ：这是智能体的本体，是配置和中间件的承载者。创建时，你需要定义它的名字、使用的模型（如 ”anthropic/claude-sonnet-4-6″ ）和系统指令。它本质上是一个中间件执行器。
2. Session（会话） ：代表一次与用户的交互会话。它封装了多轮对话（turns）的状态。当你调用 agent.run(“用户消息”) 时，内部会为这次调用创建一个Session（或复用已有的）。Session对象管理着整个对话历史（ ctx.history ）和会话级别的状态（ ctx.state ）。
3. Middleware（中间件） ：这是一切的基石。所有功能，无论是内置的还是自定义的，都通过中间件实现。每个中间件都是一个接收 (ctx, next) 的函数。 ctx 是包含当前状态、历史、请求等所有信息的上下文对象； next 是一个函数，调用它意味着“执行栈中的下一个中间件”。

3.2 统一的钩子接口与命名空间

为了精准控制智能体循环的不同阶段，Agent Express 提供了五个生命周期钩子，但它们都遵循统一的 (ctx, next) 签名。这意味着你学习一种模式，就能应用到所有场景。

• agent ：在整个智能体生命周期开始时运行（一次）。
• session ：在每次会话（Session）开始时运行。
• turn ：在每轮用户交互（Turn）开始时运行。
• model ：在每次调用大语言模型之前/之后运行。这是实现重试、预算、用量统计的关键钩子。
• tool ：在每次调用工具之前/之后运行。可用于工具权限校验、输入输出格式化、工具调用日志等。

更贴心的是，Agent Express 内置了六个开箱即用的中间件命名空间，将常见功能进行了归类，让你无需从零开始：

• guard ：守卫类中间件，如 guard.budget() （预算控制）、 guard.maxIterations() （最大迭代次数限制）。
• model ：模型相关中间件，如 model.retry() （自动重试）、 model.timeout() （调用超时）。
• observe ：观察类中间件，如 observe.usage() （令牌用量统计）、 observe.log() （结构化日志）。
• memory ：记忆管理中间件，如 memory.compaction() （历史压缩）、 memory.summary() （历史总结）。
• tools ：工具管理中间件，如 tools.function() （注册工具函数）。
• dev ：开发辅助中间件，如 dev.trace() （在控制台输出详细的执行链路追踪）。

这种设计让你能够通过直观的链式调用，组合出一个功能强大的智能体： agent.use(guard.budget()).use(model.retry()).use(tools.function(…)) 。没有复杂的编排图，没有冗长的链式类，也没有深不见底的配置对象，只有一个清晰的、可组合的中间件栈。

4. 横向对比：四大框架实现同一生产级智能体

理论说再多，不如代码有力量。让我们用四个主流的框架（Agent Express, Mastra, Vercel AI SDK, LangChain.js）来实现同一个生产级智能体需求，感受一下设计哲学带来的差异。

需求定义 ：构建一个天气查询工具调用智能体，它必须包含三个生产环境必备功能：1) 工具调用能力；2) 0.5美元的预算上限；3) 对瞬时故障（如速率限制）的自动重试。这是“最小可行生产级智能体”的基准。

4.1 Agent Express 实现

import { Agent, guard, model, tools } from “agent-express”;
import { z } from “zod”;

const agent = new Agent({
  name: “weather”,
  model: “anthropic/claude-sonnet-4-6”,
  instructions: “You are a weather assistant.”,
});

// 预算守卫：成本超过0.5美元立即停止
agent.use(guard.budget({ limit: 0.50 }));
// 模型重试：最多重试2次，初始延迟1秒（支持指数退避）
agent.use(model.retry({ maxRetries: 2, initialDelayMs: 1000 }));
// 工具注册：定义一个获取天气的工具
agent.use(tools.function({
  name: “get_weather”,
  description: “Get current weather for a city”,
  schema: z.object({ city: z.string() }),
  execute: async ({ city }) => `72°F and sunny in ${city}`,
}));

const { text } = await agent.run(“What’s the weather in Tokyo?”).result;

代码解读与优势 ：

1. 声明式与组合性 ：每个关注点（预算、重试、工具）都是一行独立的 agent.use() 调用。它们彼此解耦，你可以随意调整顺序、增删模块，而不会影响其他功能。
2. 内置最佳实践 ： Agent 构造函数自带合理的默认值，如用量追踪、最大迭代次数限制、耗时日志等。除非你用 defaults: false 显式关闭，否则这些生产就绪的功能是自动开启的。
3. 心智模型一致 ：如果你写过 app.use(cors()) 或 app.use(logger()) ，那么你就能立刻理解 agent.use(guard.budget()) 。学习成本几乎为零。

4.2 Mastra 实现

import { Agent, createTool } from “@mastra/core”;
import { z } from “zod”;

const weatherTool = createTool({
  id: “get_weather”,
  description: “Get current weather for a city”,
  inputSchema: z.object({ city: z.string() }),
  outputSchema: z.object({ result: z.string() }),
  execute: async ({ context }) => {
    return { result: `72°F and sunny in ${context.city}` };
  },
});

const agent = new Agent({
  name: “weather”,
  model: { provider: “ANTHROPIC”, name: “claude-sonnet-4-6” },
  instructions: “You are a weather assistant.”,
  tools: { get_weather: weatherTool },
});

// 注意：预算追踪和重试在Mastra中通常不是一等公民的中间件
// 它们需要在平台层配置，或通过自定义处理器/回调实现
const result = await agent.generate(“What’s the weather in Tokyo?”, {
  maxSteps: 5,
  onStepFinish: (step) => {
    // 手动成本追踪逻辑需要写在这里
    console.log(“Step: “, step.text);
  },
});
console.log(result.text);

框架定位与取舍 ：Mastra 是一个 全栈AI平台 。它的强项在于提供了开箱即用的RAG管道、工作流编排、可视化构建器和托管部署。工具定义使用独立的 createTool 工厂函数，模型配置是一个包含提供商和名称的对象。对于预算和重试这类横切关注点，Mastra更倾向于在基础设施层或通过自定义回调来处理。这是一个合理的权衡：如果你需要的是一个包含UI、部署和监控的完整解决方案，Mastra的“全家桶”模式很有价值。但如果你只需要一个灵活、轻量的智能体循环内核，它的抽象层级可能偏高，带来了不必要的复杂性。

4.3 Vercel AI SDK 实现

import { generateText, tool } from “ai”;
import { anthropic } from “@ai-sdk/anthropic”;
import { z } from “zod”;

let totalCost = 0;
const BUDGET_LIMIT = 0.50;

const result = await generateText({
  model: anthropic(“claude-sonnet-4-6”),
  system: “You are a weather assistant.”,
  prompt: “What’s the weather in Tokyo?”,
  tools: {
    get_weather: tool({
      description: “Get current weather for a city”,
      parameters: z.object({ city: z.string() }),
      execute: async ({ city }) => `72°F and sunny in ${city}`,
    }),
  },
  maxSteps: 5,
  maxRetries: 2, // 内置重试
  // 预算追踪：完全手动的命令式代码
  onStepFinish: ({ usage }) => {
    // 近似成本计算（需根据模型定价自行实现）
    const cost = (usage.promptTokens * 3 + usage.completionTokens * 15) / 1_000_000;
    totalCost += cost;
    if (totalCost > BUDGET_LIMIT) {
      throw new Error(“Budget exceeded”);
    }
  },
});

框架定位与取舍 ：Vercel AI SDK 是 面向UI的流式响应工具包 。它在React/Next.js生态中表现出色，提供了 useChat 、 useCompletion 等出色的钩子。 generateText 是一个干净的函数调用， maxRetries 也是内置参数。然而，对于预算控制这类跨领域需求，它缺乏组合抽象，迫使开发者将逻辑写成命令式代码塞进 onStepFinish 回调里。每增加一个关注点（比如再加个日志），这个回调就会变得更臃肿、更难以维护。它适合快速构建AI前端应用，但在需要高度可组合、可维护的后端智能体逻辑时，中间件模式的缺失会带来挑战。

4.4 LangChain.js 实现

import { ChatAnthropic } from “@langchain/anthropic”;
import { DynamicStructuredTool } from “@langchain/core/tools”;
import { createToolCallingAgent, AgentExecutor } from “langchain/agents”;
import { ChatPromptTemplate } from “@langchain/core/prompts”;
import { z } from “zod”;

const llm = new ChatAnthropic({
  model: “claude-sonnet-4-6”,
  maxRetries: 2, // 重试配置在LLM层
});

const weatherTool = new DynamicStructuredTool({
  name: “get_weather”,
  description: “Get current weather for a city”,
  schema: z.object({ city: z.string() }),
  func: async ({ city }) => `72°F and sunny in ${city}`,
});

const prompt = ChatPromptTemplate.fromMessages([
  [“system”, “You are a weather assistant.”],
  [“human”, “{input}”],
  [“placeholder”, “{agent_scratchpad}”],
]);

const agent = createToolCallingAgent({
  llm,
  tools: [weatherTool],
  prompt,
});

let totalCost = 0;
const executor = new AgentExecutor({
  agent,
  tools: [weatherTool],
  maxIterations: 5,
  callbacks: [{
    handleLLMEnd: (_output, _runId, _parentRunId, tags) => {
      // 在回调中手动进行成本追踪
      // 预算强制执行需要自定义回调处理器
    },
  }],
});

const result = await executor.invoke({
  input: “What’s the weather in Tokyo?”,
});
console.log(result.output);

框架定位与取舍 ：LangChain 拥有 最丰富的AI工具生态 。它的代价是巨大的概念表面积： ChatPromptTemplate 、 DynamicStructuredTool 、 createToolCallingAgent 、 AgentExecutor 、 callbacks 、 prompt placeholders 。每一个都有完善的文档，但一个新手上手前必须理解所有这些概念。预算控制等功能需要通过实现自定义的 CallbackHandler 类来完成，这带来了较高的入门门槛和模板代码。LangChain适合需要连接大量不同数据源、工具，构建极其复杂工作流的场景，但对于“一个智能体+几个横切关注点”的常见需求，它显得过于重型。

4.5 对比总结

框架	代码行数 (概略)	预算控制	自动重试	工具定义	核心抽象
Agent Express	~16行	guard.budget() (一等公民)	model.retry() (一等公民)	tools.function()	中间件
Vercel AI SDK	~26行	手动回调 ( onStepFinish )	maxRetries 参数	tool() 辅助函数	函数调用 + 回调
Mastra	~30行	平台层/自定义处理器	平台层/提供商级	createTool() 工厂函数	全栈平台对象模型
LangChain.js	~35行	自定义回调处理器	LLM构造器的 maxRetries	DynamicStructuredTool 类	链、执行器、回调

注意 ：代码行数并非唯一标准，关键在于你需要在大脑中同时维护多少概念。Agent Express 的核心概念只有一个： 中间件 。预算、重试、日志、记忆，都只是特定类型的中间件实例。这种统一性极大地降低了认知负担。

5. 洋葱模型实战：深入Agent Express中间件执行流

中间件的威力不在于减少代码行数，而在于其无与伦比的 可组合性 。让我们深入Agent Express内部，跟踪当你组合三个中间件时，一次模型调用究竟发生了什么。

假设我们注册了以下中间件：

agent.use(observe.usage()); // 第1层：令牌用量追踪
agent.use(guard.budget({ limit: 0.50 })); // 第2层：成本守卫
agent.use(model.retry({ maxRetries: 2 })); // 第3层：带退避的重试

当智能体循环需要调用LLM时，Agent Express 会将所有注册到 model 钩子的中间件组合成一个“洋葱”：

observe.usage → guard.budget → model.retry → [实际的LLM调用]

下面是每一步的详细拆解：

1. observe.usage (最外层) — 进入

   • 用量统计中间件首先被调用。它立即执行 await next() ，将控制权向内传递。在调用前它什么都不做——它的职责是在响应返回后记录用量。

2. guard.budget (中间层) — 前置检查

   • 预算守卫中间件在调用 next() 之前 开始工作。它读取 ctx.state[‘guard:budget:totalCost’] 中累计的总成本。
   • 关键决策点 ：如果累计成本已超过0.5美元，它立即抛出 BudgetExceededError 异常。流程在此中断，LLM调用永远不会发生，避免了不必要的花费。
   • 如果预算充足，它调用 await next() ，继续向内。

3. model.retry (最内层) — 弹性处理

   • 重试中间件将 await next() （即实际的LLM调用）包装在一个循环中。
   • 第一次尝试 ：它调用 next() 。如果成功，响应向外层传递。
   • 遇到可重试错误 ：如果调用抛出 RateLimitError （速率限制错误），重试中间件会等待一段时间（遵循指数退避算法，并尊重响应头中的 retry-after 信息），然后再次尝试调用 next() ，最多重复 maxRetries 次。
   • 遇到不可重试错误 ：如 AuthenticationError （认证错误），则立即将错误传播出去，不会重试。

4. LLM 响应

   • 模型提供商返回响应，其中包含用量信息： { inputTokens: 1200, outputTokens: 350 } 。

5. model.retry (最内层) — 退出

   • 由于调用成功，重试中间件将响应原样返回。

6. guard.budget (中间层) — 后置记账

   • 在 next() 解析（即LLM调用成功）后，预算守卫开始工作。
   • 它使用模型的价目表（例如，Claude Sonnet 每百万输入/输出令牌分别收费3/15美元）计算本次调用的成本。
   • 它通过一个 归约器（reducer） 将成本增量累加到 ctx.state[‘guard:budget:totalCost’] 中。同时，将一个 CostRecord 追加到 ctx.state[‘guard:budget:calls’] 数组以供审计。
   • 响应内容不变，继续向外传递。

7. observe.usage (最外层) — 退出

   • 在 next() 解析后，用量统计中间件将 response.usage 信息通过另一个归约器写入 ctx.state[‘observe:usage’] ，累加所有调用的输入和输出令牌数。
   • 最终，响应返回到智能体循环，进行后续处理（如解析工具调用）。

这个流程的精髓在于 ：这些中间件彼此 一无所知 。预算守卫不导入用量统计，重试逻辑也不导入预算守卫。它们能够组合，是因为它们都操作同一个 ModelContext ，并通过 ctx.state 中带命名空间的键进行通信。你可以移除其中任何一个、调整它们的顺序、或者添加新的中间件，而完全不需要修改其他中间件的代码。这正是Express中间件让Web服务器如此强大的原因：CORS中间件不知道速率限制，认证中间件也不知道日志记录，但它们能无缝协作。

6. 如何选择：各框架的适用场景

Agent Express 并非万能钥匙。诚实地说，在某些场景下，其他框架可能是更优的选择。下面是一个简要的选型指南。

6.1 选择 Mastra：当你需要一个全栈AI平台

如果你的项目需要开箱即用的RAG管道、可视化的工作流编排器、图形化构建界面以及托管部署，那么Mastra作为一个集成平台提供了巨大价值。你用代码的简单性换取了完整的基础设施。特别是当你希望从零开始快速部署一个带有监控的智能体，而不想自己组装各种零散部件时，Mastra的优势非常明显。

6.2 选择 Vercel AI SDK：当你深度集成React/Next.js生态

如果你的主要用例是构建具有 useChat 、 useCompletion 等流式UI的AI驱动型React/Next.js应用，Vercel AI SDK是首选。它与Vercel部署无缝集成，提供了极佳的前端开发体验。Agent Express也支持流式响应（通过 createHandler() 返回SSE），但它不内置React钩子——你需要在前端写一个简单的fetch包装器。AI SDK是 UI优先 的工具包，而Agent Express是 后端优先 的中间件框架。

6.3 选择 LangGraph：当你需要基于图的编排

如果你的智能体架构本质上是一个状态机——包含条件分支、并行执行路径、循环和状态检查点——那么LangGraph的图拓扑结构比线性的中间件栈更合适。在复杂的多智能体系统中，智能体之间以不同的状态转换进行协作，显式的图定义会更有优势。中间件模式擅长处理线性管道，而基于图的工作流则擅长处理有向无环图（DAG）或更复杂的流程。

6.4 选择 Agent Express：当你需要可组合、可维护的智能体逻辑

如果你的智能体核心是“一个带有横切关注点的模型调用循环”，那么中间件模式能给你带来最大的杠杆效应和最低的概念开销。它适合那些将智能体作为后端服务核心组件、需要精细控制每一步逻辑、并且希望代码保持高度模块化和可测试性的开发者。它继承了Web开发中经过数十年验证的中间件哲学，将其完美适配到AI智能体领域。

架构差异的本质 ：上述框架并非孰优孰劣，它们只是在不同的抽象层级上解决了不同的问题。Agent Express做了一个明确的赌注：在Web服务器中被验证了十多年的中间件模式，是组合智能体行为最合适的原语。

7. 快速入门与核心实践

7.1 5分钟创建第一个智能体

Agent Express 内置了合理的默认配置。一个包含重试、用量追踪、迭代限制和工具支持的生产就绪智能体，只需要几行代码：

import { Agent, tools } from “agent-express”;
import { z } from “zod”;

const agent = new Agent({
  name: “my-agent”,
  model: “anthropic/claude-sonnet-4-6”, // 或 “openai/gpt-4o”, “google/gemini-2.0-flash” 等
  instructions: “You are a helpful assistant.”,
});

// 注册一个工具
agent.use(tools.function({
  name: “search”,
  description: “Search the web”,
  schema: z.object({ query: z.string() }),
  execute: async ({ query }) => {
    // 这里实现你的搜索逻辑，可以调用外部API
    return `Search results for: ${query}`;
  },
}));

const { text } = await agent.run(“Find recent news about TypeScript 6.0”).result;
console.log(text);

就这样。重试逻辑、用量统计、最大迭代次数和耗时日志都通过 defaults() 中间件自动应用了。当你需要成本控制时，加上 guard.budget() ；需要结构化日志时，加上 observe.log() ；对话变长时，加上 memory.compaction() 。每个关注点都是一个独立的 use() 调用，并能与其他所有功能组合。

7.2 自定义中间件开发实战

内置中间件覆盖了常见场景，但真正的灵活性在于自定义。编写一个自定义中间件来记录每个工具调用的耗时：

import { Middleware } from “agent-express”;

// 定义一个工具钩子的中间件
const toolTimerMiddleware: Middleware = async (ctx, next) => {
  // 只对 ‘tool’ 钩子生效
  if (ctx.hook !== ‘tool’) {
    return await next(); // 不是工具钩子，直接跳过
  }

  const toolName = ctx.tool?.name || ‘unknown’;
  const startTime = Date.now();

  try {
    console.log(`[Tool Start] ${toolName} at ${new Date(startTime).toISOString()}`);
    const result = await next(); // 执行实际的工具调用或下一个中间件
    const endTime = Date.now();
    console.log(`[Tool End] ${toolName} took ${endTime – startTime}ms`);
    return result;
  } catch (error) {
    const endTime = Date.now();
    console.error(`[Tool Error] ${toolName} failed after ${endTime – startTime}ms`, error);
    throw error; // 重新抛出错误，确保错误能向上传播
  }
};

// 使用自定义中间件
agent.use(toolTimerMiddleware);

这个中间件展示了几个关键点：

1. 钩子过滤 ：通过检查 ctx.hook ，可以确保中间件只在特定的生命周期阶段执行。
2. 上下文访问 ：可以从 ctx 对象中获取丰富的信息（如工具名称 ctx.tool.name ）。
3. 错误传播 ：在catch块中重新抛出错误至关重要，否则会静默吞掉异常，破坏智能体的正常流程。
4. 与内置中间件组合 ：你可以把它放在 tools.function() 之前或之后，它都能正常工作，这就是组合性的魅力。

7.3 状态管理与中间件通信

中间件之间通过 ctx.state 对象进行松耦合的通信。这是一个键值存储，建议使用命名空间来避免冲突。

// 中间件A：收集用户反馈（模拟）
const feedbackCollector: Middleware = async (ctx, next) => {
  if (ctx.hook === ‘turn’ && ctx.turn?.role === ‘user’) {
    // 简单的情感分析（示例）
    const message = ctx.turn.content.toLowerCase();
    const sentiment = message.includes(‘thank’) ? ‘positive’ : ‘neutral’;
    // 将数据存入state，使用命名空间键
    ctx.state[‘myapp:feedback:sentiment’] = sentiment;
  }
  return await next();
};

// 中间件B：根据反馈调整响应（模拟）
const responseAdjuster: Middleware = async (ctx, next) => {
  const sentiment = ctx.state[‘myapp:feedback:sentiment’];
  const result = await next(); // 先获取模型原始响应

  if (sentiment === ‘positive’ && ctx.hook === ‘model’) {
    // 如果用户上次表达了感谢，可以在响应后追加一句友好的话
    // 注意：直接修改模型响应可能不总是合适，这里仅是示例
    console.log(`Last user sentiment was ${sentiment}, could adjust tone.`);
  }
  return result;
};

agent.use(feedbackCollector);
agent.use(responseAdjuster);

这种模式允许中间件在不直接导入彼此的情况下进行协作，极大地提升了系统的可维护性和可测试性。

8. 常见问题与排查技巧实录

在实际使用Agent Express构建智能体的过程中，你可能会遇到一些典型问题。以下是我从实战中总结的排查清单和经验。

8.1 中间件执行顺序不符合预期

问题 ：注册了多个中间件，但它们的执行顺序似乎乱了，比如日志中间件没收到完整的成本信息。 排查 ：

1. 检查注册顺序 ：中间件按照 agent.use() 的调用顺序依次注册到栈中。 执行顺序是“先进后出”（FILO）的洋葱模型 。第一个 use 的中间件位于最外层。确保你的顺序符合逻辑（例如， guard.budget() 应该在 model.retry() 的外层，以便在重试前就检查预算）。
2. 检查钩子类型 ：每个中间件可以通过 ctx.hook 判断自己处于哪个生命周期。确保你的中间件注册到了正确的钩子上（通过 agent.use(middleware, { hook: ‘model’ }) 或在内置中间件中指定）。
3. 使用 dev.trace() ：内置的 dev.trace() 中间件会在控制台输出详细的执行流水线，清晰展示每个中间件的进入和退出顺序，是调试执行流的利器。

8.2 工具无法被模型识别或调用

问题 ：已经用 tools.function() 注册了工具，但模型似乎“看不见”它，或者调用时出错。 排查 ：

1. 检查工具定义 ：确保 name 、 description 和 schema 定义清晰。 description 至关重要，模型依赖它来决定是否以及何时调用该工具。 schema 必须使用Zod等库正确定义，且与 execute 函数的参数匹配。
2. 检查模型能力 ：确认你使用的模型支持“工具调用”或“函数调用”功能。并非所有模型都支持。
3. 查看原始请求/响应 ：使用 observe.log({ level: ‘debug’ }) 中间件，它会记录发送给模型的包含工具定义的提示词，以及模型的原始响应。这能帮你确认工具定义是否被正确发送，以及模型是否尝试调用它。
4. 执行上下文 ：确保 execute 函数是异步的（ async ），并且其参数是从工具调用中正确解析出来的对象。

8.3 预算控制不生效或计算不准

问题 ：设置了 guard.budget({ limit: 0.50 }) ，但成本似乎超过了限制却没有抛出错误，或者成本计算看起来不对。 排查 ：

1. 确认模型定价 ：Agent Express内置了主流模型的定价表，但模型版本更新或自定义模型可能需要你通过 guard.budget({ limit: 0.50, modelPrices: { …customPrices } }) 提供自定义价格。检查定价配置是否正确。
2. 检查中间件位置 ： guard.budget() 必须注册在 模型调用发生之前 。如果把它注册在 session 或 agent 钩子，它可能不会在每次模型调用时触发。通常，将其注册为 model 钩子的中间件是正确的。
3. 检查 ctx.state 命名空间 ：预算中间件将累计成本存储在 ctx.state[‘guard:budget:totalCost’] 。你可以通过一个简单的观察中间件在模型调用后打印这个值来验证。
4. 令牌计数来源 ：成本计算依赖于模型返回的 usage 对象（包含 inputTokens 和 outputTokens ）。如果模型提供商没有返回准确的用量信息，成本计算将不准确。确保你的模型API支持并返回用量数据。

8.4 对话历史过长导致性能下降或超出上下文窗口

问题 ：多轮对话后，智能体响应变慢，或者开始出现“上下文长度超出限制”的错误。 解决方案 ：

1. 使用 memory.compaction() ：这是内置的解决方案。它会在对话历史达到一定长度或令牌数时，自动修剪最旧的消息，只保留最近的对话。你可以配置 maxTokens 或 maxMessages 。
2. 使用 memory.summary() ：更高级的策略。它不会直接丢弃旧消息，而是定期调用模型，将遥远的对话历史总结成一段简短的文本，然后将总结文本保留在历史中，替代原始的长篇消息。这能更好地保留长期记忆的要点。
3. 自定义记忆策略 ：你可以编写自己的记忆中间件，实现更复杂的策略，比如将历史存入向量数据库，在需要时进行检索。

8.5 如何调试复杂的中间件交互

问题 ：当多个自定义中间件和内置中间件组合时，行为变得难以预测。 调试心法 ：

1. 简化与隔离 ：首先，移除所有其他中间件，只保留问题中间件和最基本的功能进行测试。
2. 善用 ctx.state 作为调试总线 ：在每个中间件的开始和结束处，向 ctx.state 写入调试信息（例如， ctx.state[‘debug:middlewareA:entry’] = Date.now() ）。最后再通过一个中间件统一打印出来。
3. 利用 dev 命名空间 ：除了 dev.trace() ，还可以考虑编写一个 dev.inspect() 中间件，在特定钩子处将整个 ctx 对象（注意过滤敏感信息）以结构化格式（如JSON）输出到安全的地方（如日志文件），用于深度分析。
4. 单元测试中间件 ：由于中间件是纯函数 (ctx, next) => Promise ，它们非常容易进行单元测试。可以模拟 ctx 和 next 函数，断言中间件的行为是否符合预期。

构建AI智能体可以像编写Web服务器中间件一样直观和强大。Agent Express所做的，就是将这个经过时间考验的模式引入AI智能体开发领域。它可能不是所有场景的终极答案，但对于那些希望用熟悉的范式、清晰的抽象和强大的组合性来构建可靠、可维护智能体的开发者来说，它提供了一条令人愉悦的路径。最终，没有唯一正确的答案，只有在你的架构和所选抽象之间找到最合适的匹配。