AI - Langchain和LangGraph

[文档] Langchain TS版

Langchain

LangChain 六大核心模块预览：Modules、Prompts、Chains、Indexes、Memory、Agents。

信息：模型的输入和输出

new SystemMessage()：系统信息，必传，告诉模型要怎么做并为交互提供上下文。
new HumanMessage()：人类信息，就是用户输入的提示词。
new AIMessage()：为了模型的语境和消息权重，可以手动创建并插入消息历史。一般情况下为 [模型生成的响应 response]，需要将信息以数组的方式传递给模型。
new ToolMessage()：工具信息，传递工具输出的结果，通过 tool_call_id 确保工具调用请求和结果的正确匹配。
消息元数据：以 Object 格式传递。

区分 new ChatOllama() 和 createAgent()

new ChatOllama()：创建一个 LLM 实例，用于调用模型。
createAgent()：创建 Agent 智能体运行器（封装 ReAct 循环、工具调度、状态管理，里面需要传入 ChatOllama 作为模型）。
Agent = ChatOllama（模型）+ Tools + 循环调度器（createAgent）。
ChatOllama 是 Agent 的大脑；createAgent 是「大脑 + 工具 + 循环调度」的完整工作流。
createAgent 必须依赖 ChatOllama 作为模型。
createAgent 不是模型，不会独立调用 Ollama；它只是调度框架。

场景区分：

ChatOllama：简单问答、RAG，不需要 AI 自动调用函数 / 工具。

createAgent + ChatOllama：AI Agent，需要自主调用工具（读文件、执行命令、查询数据），多步骤自主完成任务。

import { createAgent } from "langchain";
const agent = createAgent({
  model: llm, // 传入上面的 ChatOllama 实例
  tools: [myTool],
  system_prompt: "你是助手",
});
const result = await agent.invoke("你好");
console.log(result.content);

学习阶段，模型推荐

使用本地的模型（Ollama：qwen3:0.6b 和 mxbai-embed-large:latest）。
RAG 使用嵌入模型和向量存储。

如果项目只需要简单问答、RAG，不需要 AI 自动调用工具和函数：

// 基础的提示词工程搭建
import { ChatOllama } from "@langchain/ollama"
import { HumanMessage } from "@langchain/core/messages"
import http from "node:http"

// 1. 创建 LLM 实例，初始化模型，指向 Ollama 本地服务
const llm = new ChatOllama({
  model: "qwen3:0.6b",
})

// 2. 使用 http 模块创建一个基本服务
const app = http.createServer(async (req, res) => {
  // 基本的调用模型，提示词工程
  const result = await llm.invoke(
  [
    ["system", "你是一个专业的翻译，能将中文翻译为英文"],
    new HumanMessage({ content: "你好，我叫合一，来自汕头。一二三四五六七八九十" })
  ])
  res.setHeader("Content-Type", "text/plain; charset=utf-8")
  res.end(result.content)
})

// 3. 监听端口
app.listen(3000, () => {
  console.log("Server is running at http://localhost:3000")
})

或使用免费的 Groq 推理 API：

// 安装
npm install @langchain/groq @langchain/core

// 模型名称参考 Groq 官网：console.groq.com
import { ChatGroq } from "@langchain/groq";
import { HumanMessage } from "@langchain/core/messages";

const model = new ChatGroq({
  apiKey: process.env.GROQ_API_KEY, // Default value.
  model: "llama-3.3-70b-versatile",
});

const message = new HumanMessage("What color is the sky?");

const res = await model.invoke([message]);

Langchain 包

包名	用途	备注
langchain	LangChain 主框架	必装
@langchain/core	核心抽象层	随 langchain 自动安装
@langchain/openai	OpenAI / Azure 模型	最常用
@langchain/ollama	Ollama	本地模型
@langchain/anthropic	Claude 系列模型	—
@langchain/groq	Groq 免费推理	学习首选
@langchain/community	海量第三方集成	按需安装
langgraph	多智能体编排	生产必装
langsmith	调试 / 监控 / 评估	推荐开发期启用

以上还有很多，具体情况具体分析。
集成：当前页有模型、工具等汇总，方便使用时参考。
- langchain-text-splitters：文本分割器，用于将文本分割为更小的块，方便模型处理。

Agent 与 Tool 调用

Agent：能够自主决策、调用工具、查看结果、继续推进，直到完成任务。

Tool：Agent 可以调用的函数，使用 tool 工具去创建。

import { tool } from "langchain";
import * as z from "zod";

// 1. 定义工具
const searchDatabase = tool(
  ({ query, limit }) => `Found ${limit} results for '${query}'`,
  {
    name: "search_database",
    description: "Search the customer database for records matching the query.",
    schema: z.object({
      query: z.string().describe("Search terms to look for"),
      limit: z.number().describe("Maximum number of results to return"),
    }),
  }
);

// 2. 导出工具集（以工具名作为 key）
export const toolsByName = {
  [searchDatabase.name]: searchDatabase,
  // ...更多工具
}
export const tools = Object.values(toolsByName)

// 3. 调用：在模型上配置工具调用，是否调用取决于用户提示词是否命中工具的 description
const modelWithTools = model.bindTools([searchDatabase]);

Memory

短期记忆 MemorySaver

短期内存（线程级持久性），在创建 Agents 时指定。
通过将这些数据存储在 graph 的状态中，agent 可以在保持不同线程间分离的同时，访问给定对话的完整上下文。

定制代理内存：通过创建带有状态模式的自定义中间件来扩展代理状态。

// 1. 使用 new StateSchema() 来定义状态，支持 Zod 对象
const CustomState = new StateSchema({
  userId: z.string(),
  preferences: z.record(z.string(), z.any())
})

// 2. 创建中间件，并通过 stateSchema 字段将自定义状态赋值
const stateExtensionMiddleware = createMiddleware({
  name: "StateExtension",
  stateSchema: CustomState,
});

// 3. 短期记忆：在创建 Agents 时指定
const checkpointer = new MemorySaver()
const agent = createAgent({
  model: "gpt-5.5",
  tools: [],
  middleware: [stateExtensionMiddleware],
  checkpointer,
});

// 4. 自定义状态可以在调用中传递
const result = await agent.invoke({
  messages: [{ role: "user", content: "Hello" }],
  userId: "user_123",
  preferences: { theme: "dark" },
});

解决短期记忆在长时间对话中超出 LLM 上下文窗口的问题：
- 修剪消息：
  - 在创建中间件时于 beforeModel 钩子中处理信息，判断当 messages 接近限制时截断，然后使用 new RemoveMessage({ id: REMOVE_ALL_MESSAGES }) 删除全部消息，再把保留的信息返回。
  - 即 messages: [new RemoveMessage({ id: REMOVE_ALL_MESSAGES }), ...newMessages]
- 删除特定消息或删除全部消息：
  - 当达到限制时，直接对 state.messages 全部截断，或对特定消息遍历 new RemoveMessage()。
  - 如果有其它要求可以看文档。
- 摘要信息：
  - 修剪和删除会直接从消息队列中剔除、丢失信息。摘要则是总结历史消息。
  - 使用内置的 summarizationMiddleware，在创建 Agents 时处理。
    1
    2
    3
    4
    5
    6
    7
    middleware: [
    summarizationMiddleware({
    model: "", // 总结用的模型
    trigger: { tokens: 4000 }, // 配置限额
    keep: { messages: 20 }, // 保留 20 条消息
    }),
    ],
访问和修改短期记忆：
- Tool：在 tool 的第一个回调函数中添加带有 ToolRuntime 的形参。
  - 形参：config: ToolRuntime<typeof CustomState.State>
  - 在函数中就可以使用 config.state.xx 获取自定义 state。
  - 修改则直接从 tool 返回状态更新，更新用 new Command() 包裹。
- 使用 dynamicSystemPromptMiddleware<ContextSchema>((_, config) => {})
  - type ContextSchema = z.infer<typeof zod对象定义的状态>;
- 创建中间件的 beforeModel 钩子。
- 创建中间件的 afterModel 钩子。

长期记忆 InMemoryStore

作用域为单个线程之外，长期记忆跨线程持续存在，并可随时调用。
有两种，都是创建一个仓库或数据库，具体看文档。

流媒体 | 事件流（langchain v1.3 推荐）

通过调用事件流返回一个带有类型化投影的运行对象，因此每个投影可以独立使用，而无需解析流模式的元组。
agent.streamEvents({ messages: [...] }, { version: "v3" })
具体参数和含义看文档：事件流 —— 内容不多，主要是教你怎么用、有哪些用处。

结构化输出的响应格式

toolStrategy 策略：默认，输出由额外的工具调用生成。
providerStrategy 策略：某些模型支持原生结构化输出。

中间件 | middleware

预构建中间件：内置可用的中间件（具体看文档）。
自定义中间件：有四个节点钩子、两个缠绕式钩子。
- beforeAgent：agent 开始前（每次调用一次）
- beforeModel：每次 model 调用前
- afterModel：每次 model 响应后
- afterAgent：agent 完成后（每次调用一次）
- wrapModelCall：围绕每个模型调用，用于重试、缓存和转换
- wrapToolCall：围绕每个工具调用，用于重试、缓存和转换
更新：返回 new Command(...) 可以更新状态。

LangGraph

定位：『代理运行时』，用于构建、管理和部署长期运行、有状态代理的低级编排框架与运行时。
与 LangChain 的关系：LangChain 提供上层抽象（快速构建），LangGraph 提供底层编排（可控、可持久化）。Agent 的运行本质就是一张「图」——节点是步骤、边是流转。
核心概念：
- State（状态）：在所有节点间流转的共享数据（类似 LangChain 的消息历史）。
- Node（节点）：一个处理函数，读取 State 并返回状态更新。
- Edge（边）：定义节点间的流转顺序；条件边可根据 State 决定下一步走向（实现分支 / 循环）。
- Checkpointer（检查点）：配合持久化存储，实现「持久执行 / 中断恢复 / 人工参与」。
擅长能力：持久执行、流式传输、人工参与（Human-in-the-loop）、持久性、低层控制。

deepagents（深度智能体）

一个建立在 LangChain 代理核心构建模块之上、并使用 LangGraph 在生产中运行的工具。
内置了使 Agents 能够执行复杂任务的工具。

以上三者的区别

LangChain【代理框架】：提供结构化内容块、代理环路和中间件等抽象功能。代理框架提供了抽象，使构建 LLM 更容易入门。
- 关键词：快速构建、标准、灵活、简单。
LangGraph【代理运行时】：用于构建、管理和部署长期运行、有状态代理的低级编排框架和运行时。
- 关键词：持久执行、流式传输、人工参与、持久性、低层控制。
Deep Agents SDK【代理线束】：基于 LangGraph 构建，增加了规划功能、用于上下文管理的文件系统、生成子代理等功能。
- 关键词：规划能力、任务委派、文件系统、Token 管理。

Feature	LangChain	LangGraph	Deep Agents
短期记忆	短期记忆	短期记忆	StateBackend
长期记忆	长期记忆	长期记忆	长期记忆
skills	多智能体技能	-	技能
次级代理	多智能体子代理	子图	次级代理
人机协同	人机环绕中间件	中断	interrupt_on参数
流媒体	Agent 流媒体	流媒体	流媒体

实践规划

搭建一个 AI 客服助手[已尝试未应用]
- 使用 createAgent() 创建一个智能体，工具可以内置几个，或通过网络调用外部的工具。
- createAgent 可以使用中间件，有几个内置的中间件很有用：
  - 摘要信息中间件 summarizationMiddleware：用于总结历史消息，避免重复信息。
  - 状态管理中间件 stateManagementMiddleware：用于管理智能体的状态，方便在不同工具之间传递信息。
- 需要注意上下文历史。
搭建一个知识库[已尝试未应用]
- 需要注意：知识库要使用嵌入模型、向量存储，还要使用工具。
- 比如 langchain-text-splitters：文本分割器，用于将文本分割为更小的块，方便模型处理。
- 比如需要用到 react-markdown + remark-gfm：将 Markdown 转换为 React 组件，方便在 Web 应用中使用。
- 文本解析器：用于解析文本、提取信息。
- 代码编辑器：用于编辑代码、生成代码。
- 流媒体：用于流式传输，方便在 Web 应用中使用。
- 查询搜索工具：用于查询知识库中的信息。

AI - Langchain和LangGraph

UUOVO

Langchain

信息：模型的输入和输出

区分 new ChatOllama() 和 createAgent()

学习阶段，模型推荐

Langchain 包

Agent 与 Tool 调用

Memory

短期记忆 MemorySaver

长期记忆 InMemoryStore

流媒体 | 事件流（langchain v1.3 推荐）

结构化输出的响应格式

中间件 | middleware

LangGraph

deepagents（深度智能体）

以上三者的区别

实践规划

其他文章

AI - Stable Diffusion 使用指南

AI - 生成式人工智能概念和原理