LangGraph 的 createReactAgent 解析

[Pines-Cheng]

这是 LangGraph 库中 createReactAgent 函数的 TypeScript 类型定义。让我为您详细解释一下：

主要功能

createReactAgent 用于创建一个基于 ReAct（Reasoning and Acting）模式的智能代理，该代理可以使用工具调用功能。

参数说明 (CreateReactAgentParams)

必需参数

• llm: 支持 OpenAI 风格工具调用的语言模型
• tools: 工具列表或 ToolNode，代理可以使用的工具集合

可选参数

提示相关

• prompt: LLM 的提示配置，可以是：
  • 字符串：转换为 SystemMessage
  • SystemMessage：直接添加到消息列表开头
  • 函数：接收完整图状态并准备 LLM 输入
  • Runnable：处理图状态并传递给 LLM

状态管理

• stateSchema: 状态模式定义
• checkpointSaver/checkpointer: 检查点保存器，用于持久化代理状态
• store: 基础存储

执行控制

• interruptBefore: 在运行前中断的节点名称列表
• interruptAfter: 在运行后中断的节点名称列表

响应格式

• responseFormat: 最终输出的结构化格式，支持：
  • Zod 模式
  • JSON 模式
  • { prompt, schema } 对象

代理配置

• name: 代理名称
• includeAgentName: 如何向 LLM 暴露代理名称
  • undefined: 依赖 LLM 提供商的 AIMessage.name
  • "inline": 直接添加到消息内容中

钩子函数

• preModelHook: 在调用 LLM 前执行的节点（如消息修剪、摘要等）
• postModelHook: 在调用 LLM 后执行的节点（如人工审核、验证等）

使用示例

import { ChatOpenAI } from "@langchain/openai";
import { tool } from "@langchain/core/tools";
import { z } from "zod";
import { createReactAgent } from "@langchain/langgraph/prebuilt";

const model = new ChatOpenAI({ model: "gpt-4o" });

const getWeather = tool((input) => {
  // 工具实现
}, {
  name: "get_weather",
  description: "获取当前天气",
  schema: z.object({
    location: z.string().describe("要查询天气的位置"),
  })
});

const agent = createReactAgent({ 
  llm: model, 
  tools: [getWeather] 
});

返回值

返回一个编译后的状态图 (CompiledStateGraph)，可以用于流式处理和状态管理。

这个函数提供了创建功能强大的 AI 代理的完整框架，支持工具调用、状态持久化、中断控制和结构化输出等高级功能。

[Pines-Cheng]

这两个参数是用于人工干预和流程控制的重要功能，让您可以在代理执行的特定节点暂停，进行人工审核或修改。

工作原理

interruptBefore

在指定节点执行前暂停，等待人工干预后再继续。

interruptAfter

在指定节点执行后暂停，可以检查结果并决定下一步操作。

典型使用场景

1. 人工审核工具调用

const agent = createReactAgent({
  llm: model,
  tools: [deleteFilesTool, sendEmailTool],
  // 在执行危险操作前暂停，等待人工确认
  interruptBefore: ["tools"]
});

// 执行时
const result = await agent.invoke(input);
// 代理会在调用工具前暂停，等待您的确认

2. 验证输出质量

const agent = createReactAgent({
  llm: model,
  tools: [researchTool],
  // 在代理给出最终回答后暂停，让人工检查
  interruptAfter: ["agent"]
});

3. 多步骤审批流程

const agent = createReactAgent({
  llm: model,
  tools: [databaseTool, apiTool],
  // 每个关键步骤都需要人工确认
  interruptBefore: ["tools"],
  interruptAfter: ["agent"]
});

实际执行流程

// 创建带中断的代理
const agent = createReactAgent({
  llm: model,
  tools: [someTool],
  interruptBefore: ["tools"]
});

// 开始执行
let state = await agent.invoke({
  messages: [{ role: "user", content: "删除所有临时文件" }]
});

// 代理在调用工具前暂停
console.log("代理想要调用工具:", state.next); // ["tools"]

// 人工审核后，可以选择：
// 1. 继续执行
state = await agent.invoke(null, { 
  configurable: { thread_id: "thread-1" } 
});

// 2. 或者修改状态后再继续
// 3. 或者终止执行

常见的节点名称

• "agent": LLM 推理节点
• "tools": 工具调用节点
• "__start__": 开始节点
• "__end__": 结束节点

使用价值

1. 安全控制: 防止代理执行危险操作
2. 质量保证: 人工验证输出质量
3. 合规要求: 满足需要人工审批的业务流程
4. 调试分析: 逐步检查代理的推理过程
5. 动态调整: 根据中间结果调整后续执行策略

这样您就可以构建既自动化又安全可控的 AI 代理系统！

[Pines-Cheng]

store 是用于跨会话持久化存储和共享数据的基础存储系统，与 checkpointSaver 不同，它主要用于存储业务数据而非执行状态。

主要用途

1. 用户数据持久化

import { InMemoryStore } from "@langchain/langgraph";

const store = new InMemoryStore();

const agent = createReactAgent({
  llm: model,
  tools: [userProfileTool],
  store: store  // 存储用户偏好、历史等
});

// 在工具中使用 store
const userProfileTool = tool(async (input, config) => {
  // 读取用户偏好
  const userPrefs = await config.store.get(
    ["user_preferences"], 
    input.userId
  );
  
  // 更新用户数据
  await config.store.put(
    ["user_preferences"], 
    input.userId, 
    { ...userPrefs, lastActive: new Date() }
  );
}, {
  name: "user_profile",
  schema: z.object({ userId: z.string() })
});

2. 知识库存储

const agent = createReactAgent({
  llm: model,
  tools: [knowledgeTool],
  store: store
});

// 存储和检索知识
const knowledgeTool = tool(async (input, config) => {
  // 从知识库检索相关信息
  const knowledge = await config.store.search(
    ["knowledge_base"], 
    input.query
  );
  
  return knowledge;
}, {
  name: "search_knowledge",
  schema: z.object({ query: z.string() })
});

3. 缓存计算结果

const expensiveComputationTool = tool(async (input, config) => {
  const cacheKey = `computation_${JSON.stringify(input)}`;
  
  // 先检查缓存
  const cached = await config.store.get(["cache"], cacheKey);
  if (cached) {
    return cached.result;
  }
  
  // 执行计算
  const result = await performExpensiveComputation(input);
  
  // 缓存结果
  await config.store.put(["cache"], cacheKey, {
    result,
    timestamp: Date.now()
  });
  
  return result;
});

4. 多代理共享数据

// 多个代理共享同一个 store
const sharedStore = new InMemoryStore();

const agent1 = createReactAgent({
  llm: model,
  tools: [dataTool],
  store: sharedStore
});

const agent2 = createReactAgent({
  llm: model,
  tools: [analysisTool],
  store: sharedStore  // 共享数据
});

Store 的数据结构

// 层次化的命名空间存储
await store.put(
  ["user_data", "preferences"],  // 命名空间路径
  "user_123",                    // 键
  { theme: "dark", lang: "zh" }  // 值
);

// 检索数据
const prefs = await store.get(
  ["user_data", "preferences"], 
  "user_123"
);

与 checkpointSaver 的区别

特性	store	checkpointSaver
用途	业务数据存储	执行状态快照
生命周期	长期持久化	会话级别
数据类型	用户数据、知识库、缓存	图状态、消息历史
访问方式	工具内主动读写	系统自动管理
共享性	可跨代理共享	绑定特定会话

常见的 Store 实现

// 1. 内存存储（开发测试）
import { InMemoryStore } from "@langchain/langgraph";
const store = new InMemoryStore();

// 2. Redis 存储（生产环境）
import { RedisStore } from "@langchain/langgraph";
const store = new RedisStore({
  client: redisClient
});

// 3. 数据库存储
import { PostgresStore } from "@langchain/langgraph";
const store = new PostgresStore({
  connectionString: "postgresql://..."
});

实际应用场景

1. 个性化推荐: 存储用户行为和偏好
2. 知识管理: 构建企业知识库
3. 缓存优化: 避免重复计算
4. 多轮对话: 保持上下文信息
5. A/B测试: 存储实验配置和结果
6. 审计日志: 记录重要操作历史

通过 store，您可以构建有"记忆"的智能代理，让它们能够学习、积累知识并提供更个性化的服务！

[Pines-Cheng]

不是的！钩子函数只在调用 LLM（语言模型） 时执行，而不是在调用工具时执行。

执行时机说明

preModelHook - LLM 调用前

• 每次代理需要调用 LLM 进行推理时执行
• 不是在调用工具时执行

postModelHook - LLM 调用后

• 每次 LLM 返回响应后执行
• 不是在工具调用完成后执行

典型的 ReAct 代理执行流程

1. 用户输入 → preModelHook → LLM推理 → postModelHook
2. LLM决定调用工具 → 执行工具 (无钩子)
3. 工具结果返回 → preModelHook → LLM推理 → postModelHook  
4. LLM给出最终答案

实际示例

const agent = createReactAgent({
  llm: model,
  tools: [weatherTool, calculatorTool],
  
  // 每次调用 LLM 前执行
  preModelHook: async (state) => {
    console.log("🤖 准备调用 LLM，当前消息数:", state.messages.length);
    
    // 消息修剪：保留最近10条消息
    if (state.messages.length > 10) {
      return {
        ...state,
        messages: [
          state.messages[0], // 保留系统消息
          ...state.messages.slice(-9) // 保留最近9条
        ]
      };
    }
    return state;
  },
  
  // 每次 LLM 响应后执行
  postModelHook: async (state) => {
    const lastMessage = state.messages[state.messages.length - 1];
    console.log("🤖 LLM 响应完成:", lastMessage.content);
    
    // 检查是否包含敏感内容
    if (containsSensitiveContent(lastMessage.content)) {
      console.log("⚠️ 检测到敏感内容，需要审核");
      // 可以修改消息或添加标记
    }
    
    return state;
  }
});

执行频率对比

一次完整对话中的执行次数：

// 用户: "今天北京天气如何？然后帮我计算 25 + 17"

// 执行流程：
// 1. preModelHook → LLM推理 → postModelHook (决定调用天气工具)
// 2. 调用 weatherTool (无钩子执行)
// 3. preModelHook → LLM推理 → postModelHook (决定调用计算工具) 
// 4. 调用 calculatorTool (无钩子执行)
// 5. preModelHook → LLM推理 → postModelHook (给出最终答案)

// 结果：preModelHook 执行 3 次，postModelHook 执行 3 次
// 工具调用 2 次，但钩子不在工具调用时执行

常见用途

preModelHook 用途：

• 消息修剪: 控制上下文长度
• 消息预处理: 格式化、翻译
• 上下文注入: 添加相关背景信息
• 成本控制: 限制 token 使用

postModelHook 用途：

• 内容审核: 检查输出合规性
• 质量验证: 验证响应格式
• 日志记录: 记录 LLM 调用情况
• 响应修改: 后处理 LLM 输出

如果想在工具调用时执行逻辑

如果您需要在工具调用前后执行逻辑，应该：

1. 在工具内部实现：

const myTool = tool(async (input, config) => {
  // 工具调用前的逻辑
  console.log("准备调用工具");
  
  const result = await actualToolLogic(input);
  
  // 工具调用后的逻辑  
  console.log("工具调用完成");
  
  return result;
});

2. 使用自定义节点：

// 创建自定义图而不是使用 prebuilt 代理

总结：钩子函数专门用于 LLM 调用的前后处理，而不是工具调用！

[Pines-Cheng]

createSupervisor 的 Python 版和 JS 版的参数不一致，JS 版本的 createSupervisor 没有提供 preModelHook/postModelHook 等钩子（Python 版有），猜测可能是更新滞后于 JS 版本。而上下文的监控和压缩是强依赖于 preModelHook 的钩子，需要想办法实现。

• JS 版：https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-supervisor/src/supervisor.ts
• Python 版：https://langchain-ai.github.io/langgraph/reference/supervisor/

createSupervisor 返回的是 StateGraph 而不是编译后的图，所以你可以在编译前添加自定义节点。

方案5：在 StateGraph 上添加自定义节点

const supervisorGraph = createSupervisor({
  agents,
  llm,
  tools,
  // 其他参数...
});

// 添加自定义的 preModelHook 节点
const graphWithHook = supervisorGraph
  .addNode("preModelHook", async (state) => {
    // 执行你的 pre-model hook 逻辑
    console.log("Pre-model hook executed with state:", state);
    
    // 你可以在这里修改 state 或执行任何自定义逻辑
    // 比如日志记录、状态验证、数据预处理等
    
    // 返回修改后的状态（或原状态）
    return state;
  })
  // 重新配置边：让所有流量先经过 preModelHook
  .addEdge(START, "preModelHook")
  .addEdge("preModelHook", "supervisor"); // 假设 supervisor 是主节点名

// 编译最终的图
const compiledGraph = graphWithHook.compile();

更精细的控制 - 拦截特定路径

如果你想更精细地控制哪些路径需要经过 hook：

const supervisorGraph = createSupervisor({
  agents,
  llm,
  tools,
  supervisorName: "supervisor",
  // 其他参数...
});

// 添加多个 hook 节点用于不同的场景
const graphWithHooks = supervisorGraph
  // 添加 supervisor 前的 hook
  .addNode("preSupervisorHook", async (state) => {
    console.log("Before supervisor call:", state);
    // 可以在这里修改发送给 supervisor 的状态
    return state;
  })
  // 添加 agent 前的 hook
  .addNode("preAgentHook", async (state) => {
    console.log("Before agent call:", state);
    // 可以在这里修改发送给 agent 的状态
    return state;
  })
  // 重新配置路由
  .addEdge(START, "preSupervisorHook")
  .addEdge("preSupervisorHook", "supervisor");

// 为每个 agent 添加 hook
for (const agent of agents) {
  graphWithHooks
    .addEdge("supervisor", "preAgentHook", (state) => {
      // 条件：当 supervisor 决定调用这个特定 agent 时
      return state.next === agent.name;
    })
    .addEdge("preAgentHook", agent.name!)
    .addEdge(agent.name!, "preSupervisorHook"); // 返回到 supervisor 前也经过 hook
}

const compiledGraph = graphWithHooks.compile();

更灵活的 Hook 系统

你甚至可以创建一个通用的 hook 系统：

interface HookConfig {
  name: string;
  hook: (state: any) => Promise<any> | any;
  before?: string; // 在哪个节点之前执行
  after?: string;  // 在哪个节点之后执行
}

function addHooksToSupervisor(
  supervisorGraph: StateGraph<any, any, any, any, any, any>,
  hooks: HookConfig[]
): StateGraph<any, any, any, any, any, any> {
  let modifiedGraph = supervisorGraph;
  
  for (const hookConfig of hooks) {
    modifiedGraph = modifiedGraph.addNode(hookConfig.name, hookConfig.hook);
    
    if (hookConfig.before) {
      // 找到所有指向 hookConfig.before 的边，重定向到 hook
      // 然后从 hook 连接到原目标
      modifiedGraph = modifiedGraph
        .addEdge(hookConfig.name, hookConfig.before);
      // 这里需要更复杂的逻辑来重定向现有的边
    }
    
    if (hookConfig.after) {
      // 类似的逻辑处理 after hook
      modifiedGraph = modifiedGraph
        .addEdge(hookConfig.after, hookConfig.name);
    }
  }
  
  return modifiedGraph;
}

// 使用示例
const supervisorGraph = createSupervisor({
  agents,
  llm,
  tools,
});

const graphWithHooks = addHooksToSupervisor(supervisorGraph, [
  {
    name: "loggerHook",
    hook: async (state) => {
      console.log("State transition:", state);
      return state;
    },
    before: "supervisor"
  },
  {
    name: "validationHook", 
    hook: async (state) => {
      // 验证状态
      if (!state.messages || state.messages.length === 0) {
        throw new Error("Invalid state: no messages");
      }
      return state;
    },
    before: "supervisor"
  }
]);

const compiledGraph = graphWithHooks.compile();

优势

这种方法的优势：

1. 完全控制：你可以精确控制数据流和执行顺序
2. 灵活性：可以添加多个 hook 节点，处理不同的场景
3. 可观测性：可以在图的可视化中看到你的 hook 节点
4. 状态修改：可以在 hook 中修改状态，影响后续节点
5. 无侵入性：不需要修改 createSupervisor 源码

这确实是一个很棒的解决方案！你想实现哪种类型的 hook 逻辑？