在构建复杂AI代理应用时，选择合适的框架组合至关重要。LangChain.js/LangGraph.js/DeepAgents.js/LangSmith.js这一技术栈通过分层设计，为开发者提供了从基础组件到高级抽象，再到生产监控的全链路支持。该技术栈特别适合需要工具调用、多代理协作、长期记忆和复杂工作流编排的生产级Agent应用，但其成功部署需要深入理解各组件的定位与协同关系，并在开发过程中采取相应的最佳实践。

一、技术栈定位与协同关系

LangChain.js/LangGraph.js/DeepAgents.js/LangSmith.js形成了一套完整的智能体开发生态系统，各组件在技术栈中扮演不同角色：

  1. LangChain.js - 基础层：

    • 提供构建线性、可预测工作流程的工具
    • 支持工具调用、提示模板、输出解析等核心功能
    • 通过tool()函数和createReactAgent实现简单代理逻辑
    • 定位：相当于"编剧"，负责编写固定的对话流程和任务执行顺序

  2. LangGraph.js - 流程管理层：

    • 基于LangChain.js构建，引入有向图结构处理复杂工作流
    • 支持状态机、循环、条件分支等高级控制流
    • 提供StateGraph、StateSchema等API管理代理状态和流程
    • 定位：相当于"导演"，协调代理间的交互，处理复杂的推理流程和决策路径

  3. DeepAgents.js - 智能体抽象层：

    • 构建在LangChain.js和LangGraph.js之上的高级抽象
    • 封装任务规划、子代理管理、文件系统等通用能力
    • 提供createDeepAgent等高级API简化复杂代理开发
    • 定位：相当于"智能模块"，提供开箱即用的高级代理功能，使开发变得像"搭积木"一样简单

  4. LangSmith - 可观测性层：

    • 提供调试、测试和监控大语言模型应用程序的平台
    • 通过环境变量自动启用追踪（LANGCHAIN_TRACING_V2），无需代码集成
    • 支持链路追踪、日志记录、性能监控和成本分析
    • 定位：相当于“剪辑师”，在生产环境中提供可见性和控制力，帮助优化最终系统表现

这四个组件并非竞争对手，而是互补的技术栈。在构建复杂智能体应用时，它们的协同关系为：LangChain.js处理基础链式逻辑 → LangGraph.js管理复杂状态和流程 → DeepAgents.js提供开箱即用的智能体功能 → LangSmith.js保障生产可靠性。这种分层设计使开发者能够专注于业务逻辑，同时确保系统的稳定性和可维护性。

二、工具调用实现方案

复杂智能体应用的核心能力之一是工具调用。以下是基于该技术栈实现工具调用的几种方法：

1. 基础工具调用（LangChain.js）

LangChain.js提供了最基础的工具调用机制：

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

// 定义工具（使用 zod schema 声明参数类型）
const webSearchTool = tool(
  async ({ query }) => {
    const response = await fetch(`https://api.example.com/search?q=${encodeURIComponent(query)}`);
    const data = await response.json();
    return data.content;
  },
  {
    name: "web_search",
    description: "搜索互联网获取时事新闻或特定网页内容",
    schema: z.object({
      query: z.string().describe("搜索关键词"),
    }),
  }
);

// 定义语言模型
const model = new ChatOpenAI({ model: "gpt-4", temperature: 0 });

// 创建代理（推荐使用 createReactAgent）
const agent = createReactAgent({
  llm: model,
  tools: [webSearchTool],
});

// 执行代理
const result = await agent.invoke({
  messages: [{ role: "user", content: "什么是最新的AI技术趋势？" }],
});

实现要点：

  • 工具通过tool(func, {name, description, schema})定义，schema使用 zod 声明参数类型
  • 推荐使用createReactAgent（基于 LangGraph 预构建）替代旧的AgentExecutor
  • 生产环境中应添加输入验证、速率限制和异常处理机制
  • LangSmith 追踪通过环境变量自动启用，无需代码集成
2. 高级工具调用（DeepAgents.js）

DeepAgents.js在此基础上提供了更高级的工具调用抽象：

import * as z from "zod";
import { createDeepAgent } from "deepagents";
import { tool } from "langchain";
import { ChatOpenAI } from "@langchain/openai";

// 定义自定义工具
const webSearchTool = tool(
  async ({ query }) => {
    // 实现搜索逻辑
    const response = await fetch(`https://api.example.com/search?q=${encodeURIComponent(query)}`);
    const data = await response.json();
    return JSON.stringify(data);
  },
  {
    name: "web_search",
    description: "搜索互联网获取信息",
    schema: z.object({
      query: z.string().describe("搜索关键词"),
    }),
  }
);

// 创建深度智能体
const researchAgent = createDeepAgent({
  tools: [webSearchTool],  // 自定义工具 + 内置 write_todos、task 等
  systemPrompt: "你是一个专业的研究助手，善于搜索、分析和整理信息。",
});

// 执行代理
const result = await researchAgent.invoke({
  messages: [{
    role: "user",
    content: "请研究大型语言模型的最新发展"
  }],
});

实现要点：

  • createDeepAgent接受tools（自定义工具数组）和systemPrompt（系统提示词）
  • 内置write_todos工具自动进行任务规划和分解，无需手动配置
  • 内置task工具可委派子代理处理子任务，实现多代理协作
  • 内置虚拟文件系统自动管理上下文，大结果会卸载到文件中避免上下文溢出

三、多代理协作实现方案

多代理协作是构建复杂智能体应用的关键挑战。以下是基于该技术栈的实现方案：

1. 基于LangGraph.js的图结构协作

LangGraph.js通过图结构实现多代理协作：

import * as z from "zod/v4";
import { StateGraph, StateSchema, MessagesValue, START, END } from "@langchain/langgraph";
import { ChatOpenAI } from "@langchain/openai";

// 使用 StateSchema + zod 定义状态
const ResearchState = new StateSchema({
  messages: MessagesValue,  // 消息列表（内置 reducer 自动追加）
  topic: z.string(),
  progress: z.number().default(0),
  results: z.array(z.string()).default(() => []),
});

const model = new ChatOpenAI({ model: "gpt-4", temperature: 0 });

// 创建状态图
const workflow = new StateGraph(ResearchState)
  // 节点是接收 state、返回 partial update 的函数
  .addNode("plan_task", async (state) => {
    const response = await model.invoke([
      { role: "system", content: "你是一个任务规划专家" },
      { role: "user", content: `请规划关于「${state.topic}」的研究任务` },
    ]);
    return { messages: [response], progress: state.progress + 33 };
  })
  .addNode("collect_data", async (state) => {
    const response = await model.invoke([
      { role: "system", content: "你是一个数据收集专家" },
      { role: "user", content: `收集关于「${state.topic}」的数据` },
    ]);
    return {
      messages: [response],
      results: [...state.results, response.content as string],
      progress: state.progress + 33,
    };
  })
  .addNode("analyze_results", async (state) => {
    const response = await model.invoke([
      { role: "system", content: "你是一个数据分析专家" },
      { role: "user", content: `分析以下结果：\n${state.results.join("\n")}` },
    ]);
    return { messages: [response], progress: 100 };
  })
  // 定义边
  .addEdge(START, "plan_task")
  .addEdge("plan_task", "collect_data")
  .addEdge("collect_data", "analyze_results")
  // 条件边：路由函数决定下一步
  .addConditionalEdges("analyze_results", (state) => {
    return state.progress < 100 ? "collect_data" : END;
  });

// 编译并执行
const app = workflow.compile();
const result = await app.invoke({
  messages: [],
  topic: "大型语言模型的最新发展",
  progress: 0,
  results: [],
});

实现要点：

  • 状态通过StateSchema + zod 定义，MessagesValue提供消息感知的 reducer
  • 节点是(state) => partialUpdate函数，只需返回要更新的字段，无需返回完整状态
  • addEdge(from, to)定义静态路由，addConditionalEdges(from, router, mapping?)定义动态路由
  • 必须调用.compile()后才能执行，通过.invoke()或.stream()运行
2. 基于DeepAgents.js的子代理协作

DeepAgents.js提供了更高级的子代理协作抽象：

import { createDeepAgent } from "deepagents";

// 创建主代理 — 内置 task 工具自动支持子代理派遣
const mainAgent = createDeepAgent({
  tools: [],  // 可添加自定义工具，子代理能力已内置
  systemPrompt: `你是一个研究主管。对于复杂任务，使用 task 工具派遣子代理处理。
每个子代理在独立的上下文窗口中工作，完成后返回结果。`,
});

// 主代理会自动使用内置 task 工具派遣子代理
const result = await mainAgent.invoke({
  messages: [{
    role: "user",
    content: "请研究大型语言模型的最新发展，派遣不同的子代理分别处理文献搜索和数据分析，最后整合结果撰写报告"
  }],
});

// 子代理派遣由 LLM 自主决策，无需手动调用
// 主代理会通过 task 工具：
// 1. 派遣子代理A处理文献搜索
// 2. 派遣子代理B处理数据分析
// 3. 等待子代理完成后整合结果
// 4. 撰写最终报告

实现要点：

  • DeepAgents 内置task工具自动支持子代理派遣，无需手动创建子代理工具
  • 子代理在独立的上下文窗口中运行，实现上下文隔离
  • 支持异步子代理（后台运行），可通过进度检查、跟踪和取消进行管理
  • 主代理通过 LLM 自主决策何时派遣子代理、如何整合结果

四、长期记忆实现方案

长期记忆是复杂智能体应用的另一个关键挑战。以下是基于该技术栈的实现方案：

1. 基于LangChain.js的向量存储记忆

LangChain.js支持多种向量数据库实现长期记忆：

import { VectorStoreRetrieverMemory } from "langchain/memory";
import { MemoryVectorStore } from "langchain/vectorstores/memory";
import { OpenAIEmbeddings } from "langchain/embeddings/openai";

// 初始化向量存储
const vectorStore = new MemoryVectorStore(new OpenAIEmbeddings());

// 创建基于向量库的长期记忆
const memory = new VectorStoreRetrieverMemory({
  // 每次查询返回最相关的 k 条记忆
  vectorStoreRetriever: vectorStore.asRetriever(4),
  memoryKey: "history",  // 记忆在 prompt 中的变量名
});

// 保存记忆（通常由 chain 自动调用）
await memory.saveContext(
  { input: "用户喜欢简洁的回答" },
  { output: "好的，我会保持简洁" }
);

// 检索相关记忆
const result = await memory.loadMemoryVariables({
  prompt: "用户的偏好是什么？"
});
// result: { history: 'input: 用户喜欢简洁的回答\noutput: 好的，我会保持简洁' }

// 在 chain 中使用记忆
import { LLMChain } from "langchain/chains";
import { PromptTemplate } from "langchain/prompts";
import { ChatOpenAI } from "@langchain/openai";

const prompt = PromptTemplate.fromTemplate(`
以下是之前的对话记录：
{history}

当前对话：
用户: {input}
AI:
`);

const chain = new LLMChain({
  llm: new ChatOpenAI({ model: "gpt-4", temperature: 0 }),
  prompt,
  memory,  // 自动在每次调用前后保存和检索记忆
});

const response = await chain.call({ input: "继续之前的研究任务" });

实现要点：

  • 使用VectorStoreRetrieverMemory将记忆存储在向量数据库中，支持基于语义相似度的记忆检索
  • 通过vectorStoreRetriever参数控制每次检索返回的记忆条数（k值）
  • 生产环境中建议使用持久化的向量数据库（如Pinecone、Weaviate、Chroma）替代MemoryVectorStore
  • 记忆通过memoryKey注入到 prompt 中，需与 prompt template 中的变量名对应
2. 基于DeepAgents.js的文件系统记忆

DeepAgents.js提供了文件系统工具实现长期记忆：

import { createDeepAgent } from "deepagents";

// 创建代理 — 内置虚拟文件系统工具自动可用
const agent = createDeepAgent({
  tools: [],  // 内置工具包括 write_file、read_file、edit_file
  systemPrompt: "你是一个研究助手。请使用文件系统工具保存和检索研究数据。",
});

// 代理自动使用内置文件系统工具保存记忆
const result = await agent.invoke({
  messages: [{
    role: "user",
    content: "搜索大型语言模型的最新发展，并将结果保存到 research-notes.md"
  }],
});

// 代理从文件系统检索之前的研究记忆
const followUp = await agent.invoke({
  messages: [
    ...result.messages,
    { role: "user", content: "检索之前保存的研究笔记，并基于此撰写总结" },
  ],
});

实现要点：

  • DeepAgents 内置write_file、read_file、edit_file等虚拟文件系统工具
  • 虚拟文件系统由后端（backend）支持，可选本地文件系统或云沙箱（Modal、Runloop）
  • 无需手动配置memory参数，代理通过工具自主管理持久化数据
  • 生产环境中建议使用云沙箱后端，避免本地文件系统的限制

五、工作流编排实现方案

工作流编排是构建复杂智能体应用的核心能力。以下是基于该技术栈的实现方案：

1. 基于LangGraph.js的DAG工作流编排

LangGraph.js通过有向无环图（DAG）实现复杂工作流编排：

import * as z from "zod/v4";
import { StateGraph, StateSchema, MessagesValue, START, END } from "@langchain/langgraph";
import { ChatOpenAI } from "@langchain/openai";

// 使用 StateSchema + zod 定义工作流状态
const ResearchState = new StateSchema({
  messages: MessagesValue,
  task: z.string(),
  subtasks: z.array(z.string()).default(() => []),
  progress: z.number().default(0),
  results: z.array(z.string()).default(() => []),
});

const model = new ChatOpenAI({ model: "gpt-4", temperature: 0 });

// 创建状态图（链式调用）
const workflow = new StateGraph(ResearchState)
  .addNode("plan_task", async (state) => {
    const response = await model.invoke([
      { role: "system", content: "你是一个任务规划专家" },
      { role: "user", content: `为「${state.task}」生成研究计划` },
    ]);
    return { messages: [response], progress: 25 };
  })
  .addNode("collect_data", async (state) => {
    const response = await model.invoke([
      { role: "system", content: "你是一个数据收集专家" },
      { role: "user", content: `收集关于「${state.task}」的数据` },
    ]);
    return {
      messages: [response],
      results: [...state.results, response.content as string],
      progress: state.progress + 25,
    };
  })
  .addNode("analyze_results", async (state) => {
    const response = await model.invoke([
      { role: "system", content: "你是一个数据分析专家" },
      { role: "user", content: `分析以下结果：\n${state.results.join("\n")}` },
    ]);
    return { messages: [response], progress: state.progress + 25 };
  })
  .addNode("write_report", async (state) => {
    const response = await model.invoke([
      { role: "system", content: "你是一个报告撰写专家" },
      { role: "user", content: `基于以下分析结果撰写报告：\n${state.results.join("\n")}` },
    ]);
    return { messages: [response], progress: 100 };
  })
  // 静态边
  .addEdge(START, "plan_task")
  .addEdge("plan_task", "collect_data")
  .addEdge("collect_data", "analyze_results")
  .addEdge("analyze_results", "write_report")
  // 条件边：数据不足时回到收集步骤
  .addConditionalEdges("write_report", (state) => {
    return state.results.length === 0 ? "collect_data" : END;
  });

// 编译并执行
const app = workflow.compile();
const result = await app.invoke({
  messages: [],
  task: "研究大型语言模型的最新发展",
  subtasks: [],
  progress: 0,
  results: [],
});

实现要点：

  • StateSchema + zod 提供类型安全的状态定义，MessagesValue自动追加消息
  • 节点函数只返回 partial update，框架自动合并到现有状态
  • addConditionalEdges(from, router)实现动态路由，支持循环和分支
  • 必须.compile()后才能执行，通过.invoke()或.stream()运行
2. 基于DeepAgents.js的任务分解编排

DeepAgents.js提供了更高级的任务分解抽象：

import { createDeepAgent } from "deepagents";

// 创建智能体 — 内置 write_todos 工具自动提供任务分解能力
const agent = createDeepAgent({
  tools: [],  // write_todos、task 等内置工具自动可用
  systemPrompt: `你是一个研究助手。请按照以下步骤工作：
1. 使用 write_todos 制定研究计划
2. 逐一完成每个子任务
3. 使用文件系统保存中间结果
4. 最后整合所有结果撰写报告`,
});

// 代理自动进行任务分解和执行
const result = await agent.invoke({
  messages: [{
    role: "user",
    content: "请研究大型语言模型的最新发展，制定研究计划并逐步执行，最后撰写研究报告"
  }],
});

// 代理内部流程：
// 1. write_todos: 创建任务清单（如“收集文献”“分析趋势”“撰写报告”）
// 2. 逐一调用工具完成每个子任务
// 3. 使用虚拟文件系统保存中间结果
// 4. 整合所有结果撰写最终报告

实现要点：

  • DeepAgents 内置write_todos工具自动进行任务分解和追踪，无需手动配置
  • 代理通过 LLM 自主决策执行顺序，无需手动控制工作流循环
  • 内置task工具可派遣子代理处理复杂子任务
  • 结合 LangGraph.js 的图结构可实现更复杂的工作流依赖关系

六、生产环境部署最佳实践

将复杂智能体应用部署到生产环境需要特别关注性能、可靠性和安全性。以下是基于该技术栈的生产环境部署最佳实践：

1. 架构设计与部署

推荐使用微服务架构，每个代理作为独立服务部署，提高系统的可扩展性和容错性：

// 代理服务示例
import express from 'express';
import { createDeepAgent } from "deepagents";
import { tool } from "langchain";
import * as z from "zod";

const app = express();
const port = 3000;

// LangSmith 通过环境变量自动启用追踪，无需代码初始化
// 设置以下环境变量：
// LANGCHAIN_TRACING_V2=true
// LANGCHAIN_API_KEY=your-api-key
// LANGCHAIN_PROJECT=research-agent

// 定义自定义工具
const webSearchTool = tool(
  async ({ query }) => {
    const response = await fetch(`https://api.example.com/search?q=${encodeURIComponent(query)}`);
    const data = await response.json();
    return JSON.stringify(data);
  },
  {
    name: "web_search",
    description: "搜索互联网获取信息",
    schema: z.object({ query: z.string().describe("搜索关键词") }),
  }
);

// 初始化代理
const agent = createDeepAgent({
  tools: [webSearchTool],
  systemPrompt: "你是一个专业的研究助手。",
});

// API路由处理代理调用
app.post('/invoke', async (req, res) => {
  try {
    const result = await agent.invoke({
      messages: [{
        role: "user",
        content: req.body.content,
      }],
    });

    res.json({
      success: true,
      messages: result.messages,
    });
  } catch (error) {
    res.status(500).json({
      success: false,
      error: error.message,
    });
  }
});

// 启动服务
app.listen(port, () => {
  // eslint-disable-next-line no-console
  console.log(`代理服务已启动，端口：${port}`);
});

部署要点：

  • 使用Docker容器化部署，确保环境一致性
  • 配置Nginx反向代理和HTTPS证书，提升服务安全性
  • 使用Kubernetes管理服务集群，实现自动扩缩容和故障恢复
  • 为不同类型的代理配置独立的服务，避免相互干扰
2. 监控与可观测性（LangSmith.js）

LangSmith.js是生产环境监控的关键组件，提供完整的可观测性：

// LangSmith 追踪完全通过环境变量配置，无需代码集成
// 在启动服务前设置以下环境变量：
// LANGCHAIN_TRACING_V2=true        — 启用追踪
// LANGCHAIN_API_KEY=lsv2_sk_...    — API密钥
// LANGCHAIN_PROJECT=research-agent — 项目名称
// LANGCHAIN_ENDPOINT=https://api.smith.langchain.com — 追踪端点（默认）

// 代理服务示例（自动追踪）
// 只要设置了环境变量，LangChain/LangGraph 的所有操作自动被追踪
import express from "express";
import { createReactAgent } from "@langchain/langgraph/prebuilt";
import { ChatOpenAI } from "@langchain/openai";

const app = express();

const model = new ChatOpenAI({ model: "gpt-4", temperature: 0 });
const agent = createReactAgent({ llm: model, tools: [] });

app.post('/invoke', async (req, res) => {
  try {
    // LangSmith 自动追踪此调用（包括输入/输出/token 用量）
    const result = await agent.invoke({
      messages: [{ role: "user", content: req.body.content }],
    });

    res.json({ success: true, messages: result.messages });
  } catch (error) {
    res.status(500).json({ success: false, error: error.message });
  }
});

// 启动服务
// LANGCHAIN_TRACING_V2=true LANGCHAIN_PROJECT=prod node server.js
app.listen(3000);

监控要点：

  • LangSmith 追踪通过环境变量自动启用，无需代码集成（无 init()/trace()/span() API）
  • LangChain.js 和 LangGraph.js 的所有操作自动被追踪，包括输入/输出/token 用量
  • 通过LANGCHAIN_PROJECT环境变量区分不同环境（dev/staging/prod）的追踪数据
  • 在 LangSmith 平台上可查看追踪详情、设置报警和性能分析
3. 安全与权限控制

安全是生产环境部署的首要考虑：

// 安全配置示例（纯概念性配置，需根据实际框架调整）
const securityConfig = {
  // 工具权限控制
  toolPermissions: {
    webSearch: {
      allowedDomains: ["example.com", "api.langchain.dev"],
      queryLimits: {
        maxResults: 10,
        timeout: 5000,
      },
    },
    fileWrite: {
      allowedPaths: ["./agent-memory"],
      sizeLimits: {
        maxSize: 1048576,   // 1MB
        totalSize: 5242880, // 5MB
      },
    },
    apiCall: {
      allowedAPIs: ["https://api.langchain.dev/v1"],
      authRequired: true,
    },
  },

  // 沙箱配置（云沙箱后端）
  sandboxConfig: {
    type: "modal",  // 或 "runloop"、"local"
    options: {
      memoryLimit: "512m",
      cpuQuota: 50000,
      networkAccess: {
        allowed: ["api.langchain.dev", "example.com"],
        restricted: ["*"],
      },
    },
  },

  // 记忆访问控制
  memoryConfig: {
    encryption: true,
    accessControl: {
      public: ["userPrompt", "finalResult"],
      private: ["intermediateSteps", "sensitiveInfo"],
    },
  },
};

// 在创建工具时应用权限限制
const restrictedSearchTool = tool(
  async ({ query }) => {
    const { allowedDomains } = securityConfig.toolPermissions.webSearch;
    // 在工具逻辑中应用域名限制
    const response = await fetch(`https://api.example.com/search?q=${encodeURIComponent(query)}`);
    const data = await response.json();
    return JSON.stringify(data);
  },
  {
    name: "web_search",
    description: "搜索互联网获取信息（受域名限制）",
    schema: z.object({ query: z.string().describe("搜索关键词") }),
  }
);

安全要点：

  • 为每个工具设置明确的权限边界和使用限制
  • 使用沙箱后端（如Modal、Runloop）隔离代理执行，防止对主机系统的未授权访问
  • 实现代理身份验证和授权机制，确保系统安全
  • 定期审计代理行为，及时发现和处理异常
4. 性能优化与扩展

生产环境需要关注系统性能和可扩展性：

// 性能优化示例

// 1. 使用 Redis 向量存储替代内存向量存储（提升生产环境性能）
import { RedisVectorStore } from "@langchain/community/vectorstores/redis";
import { OpenAIEmbeddings } from "@langchain/openai";

const redisVectorStore = new RedisVectorStore(new OpenAIEmbeddings(), {
  redisClient: await createRedisClient({
    url: process.env.REDIS_URL,
  }),
  indexName: "research-memory",
});

// 2. 使用 LangGraph 的 checkpointer 实现状态持久化
import { RedisSaver } from "@langchain/langgraph-checkpoint-redis";

const checkpointer = new RedisSaver({
  connection: { url: process.env.REDIS_URL },
});

const workflow = workflowBuilder.compile({ checkpointer });
// 现在工作流状态会持久化到 Redis，支持恢复和续接

// 3. 并发请求处理
import express from "express";
import pLimit from "p-limit";

const app = express();
const limit = pLimit(10); // 限制并发数为 10

app.post('/invoke', (req, res) => {
  limit(async () => {
    try {
      const result = await agent.invoke({
        messages: [{ role: "user", content: req.body.content }],
      });
      res.json({ success: true, messages: result.messages });
    } catch (error) {
      res.status(500).json({ success: false, error: error.message });
    }
  });
});

性能优化要点：

  • 使用 Redis 向量存储替代MemoryVectorStore提升生产环境性能和持久化能力
  • 通过 LangGraph 的 checkpointer（如RedisSaver）实现工作流状态持久化和恢复
  • 使用p-limit等并发控制库限制同时处理的请求数
  • 使用缓存机制减少重复计算和资源消耗
  • 定期清理和优化记忆存储，保持系统高效运行

七、常见挑战与解决方案

在构建生产级Agent应用时，开发者会面临一系列挑战。以下是基于该技术栈的常见挑战与解决方案：

1. 上下文窗口限制

挑战：大型语言模型的上下文窗口限制导致长流程任务难以处理。

解决方案：

  • 使用DeepAgents.js的file_write和file_read工具将大型上下文卸载到文件系统
  • 结合LangChain.js的Summarize工具对长文本进行摘要，减少上下文长度
  • 采用分块处理策略，将大型任务分解为多个小步骤
  • 实现记忆的自动清理和优化机制，移除不相关或过时信息
// 上下文窗口优化示例
import * as z from "zod";
import { tool } from "langchain";
import { ChatOpenAI } from "@langchain/openai";

// 定义摘要工具
const summarizeTool = tool(
  async ({ text }) => {
    const model = new ChatOpenAI({ model: "gpt-3.5-turbo", temperature: 0 });
    const result = await model.invoke([
      { role: "user", content: `请对以下文本进行摘要，保留关键信息：\n${text}` },
    ]);
    return result.content as string;
  },
  {
    name: "summarize",
    description: "对长文本进行摘要，减少上下文长度",
    schema: z.object({ text: z.string().describe("要摘要的长文本") }),
  }
);

// DeepAgents 内置的虚拟文件系统自动处理上下文溢出
// 大结果会自动卸载到文件，避免上下文窗口溢出
const agent = createDeepAgent({
  tools: [summarizeTool],
  systemPrompt: `你是一个研究助手。对于长文本，使用 summarize 工具进行摘要。
大结果会自动保存到文件系统，请使用 read_file 检索之前的结果。`,
});

// 代理会自动管理上下文窗口，无需手动覆写 invoke 方法
const result = await agent.invoke({
  messages: [{ role: "user", content: "请研究并总结大型语言模型的最新发展" }],
});
2. 多代理协作冲突

挑战：多代理协作时可能出现状态冲突和资源竞争。

解决方案：

  • 使用版本控制和锁机制管理共享状态
  • 实现冲突检测和解决策略，确保工作流一致性
  • 为每个代理分配唯一的ID和作用域，减少冲突
  • 使用事件驱动架构处理异步协作，避免阻塞和死锁
// 多代理协作冲突解决方案
import { createDeepAgent } from "deepagents";

// 使用内置 task 工具实现子代理协作，无需手动管理代理 ID 和状态
const mainAgent = createDeepAgent({
  tools: [],  // task 工具已内置
  systemPrompt: `你是一个研究主管。对于复杂任务，使用 task 工具派遣子代理处理。
每个子代理在独立上下文窗口中工作，完成后返回结果。
子代理间不会共享状态，请通过整合返回结果来协调。`,
});

// 主代理自动通过 task 工具派遣子代理并整合结果
const result = await mainAgent.invoke({
  messages: [{
    role: "user",
    content: "请同时派遣子代理处理文献搜索和数据分析，然后整合结果"
  }],
});

// 如果需要更细粒度的控制，可使用 LangGraph 图结构实现：
// - 每个节点作为独立代理，通过状态传递实现协作
// - LangGraph 的 StateSchema reducer 自动处理状态合并，避免冲突
3. 复杂推理的可解释性

挑战：复杂多步骤推理的决策过程难以解释和验证。

解决方案：

  • 利用LangSmith.js的完整追踪功能记录每个步骤的详细信息
  • 实现代理推理的可视化工具，便于理解和分析
  • 添加代理决策的验证层，确保关键决策的合理性
  • 支持代理行为的解释生成，帮助用户理解系统决策
// 复杂推理可解释性解决方案
// LangSmith 追踪通过环境变量自动启用（LANGCHAIN_TRACING_V2=true）
// 追踪数据可在 LangSmith 平台上查看：https://smith.langchain.com

import { ChatOpenAI } from "@langchain/openai";
import { CallbackManager } from "@langchain/core/callbacks/manager";

// 使用 callback 记录代理执行过程（LangChain.js 原生支持）
const steps: Array<{ step: string; result: string }> = [];

const callbackManager = CallbackManager.fromHandlers({
  handleLLMEnd: async (output) => {
    steps.push({
      step: "llm_output",
      result: typeof output.generations[0]?.[0]?.text === "string"
        ? output.generations[0][0].text
        : JSON.stringify(output.generations[0]?.[0]?.text),
    });
  },
  handleToolEnd: async (output) => {
    steps.push({ step: "tool_output", result: output });
  },
});

const model = new ChatOpenAI({
  model: "gpt-4",
  temperature: 0,
  callbacks: callbackManager,
});

// 执行代理调用（自动记录每个步骤）
const result = await model.invoke(
  [{ role: "user", content: "研究大型语言模型的最新发展" }],
);

// 生成决策解释
const explanationModel = new ChatOpenAI({ model: "gpt-4", temperature: 0 });
const explanation = await explanationModel.invoke([
  { role: "user", content: `基于以下代理执行过程，解释为什么代理做出了这个决策：\n${JSON.stringify(steps, null, 2)}` },
]);

八、实际应用案例

以下是一个基于该技术栈构建的完整研究助手Agent应用案例：

import express from "express";
import * as z from "zod/v4";
import {
  StateGraph,
  StateSchema,
  MessagesValue,
  START,
  END,
} from "@langchain/langgraph";
import { createDeepAgent } from "deepagents";
import { tool } from "langchain";
import { ChatOpenAI } from "@langchain/openai";

const app = express();
app.use(express.json());
const port = 3000;

// LangSmith 追踪通过环境变量自动启用：
// LANGCHAIN_TRACING_V2=true
// LANGCHAIN_API_KEY=lsv2_sk_...
// LANGCHAIN_PROJECT=research-assistant

// 使用 StateSchema + zod 定义研究助手状态
const ResearchState = new StateSchema({
  messages: MessagesValue,
  topic: z.string(),
  subtasks: z.array(z.string()).default(() => []),
  progress: z.number().default(0),
  results: z.array(z.string()).default(() => []),
});

const model = new ChatOpenAI({ model: "gpt-4", temperature: 0 });

// 定义搜索工具
const webSearchTool = tool(
  async ({ query }) => {
    const response = await fetch(`https://api.example.com/search?q=${encodeURIComponent(query)}`);
    const data = await response.json();
    return JSON.stringify(data);
  },
  {
    name: "web_search",
    description: "搜索互联网获取信息",
    schema: z.object({ query: z.string().describe("搜索关键词") }),
  }
);

// 创建 LangGraph 状态图
const workflow = new StateGraph(ResearchState)
  .addNode("plan_research", async (state) => {
    const response = await model.invoke([
      { role: "system", content: "你是一个任务规划专家。请返回JSON格式的计划。" },
      { role: "user", content: `请规划关于「${state.topic}」的研究任务，返回子任务列表` },
    ]);
    return { messages: [response], progress: 25 };
  })
  .addNode("collect_data", async (state) => {
    const response = await model.invoke([
      { role: "system", content: "你是一个数据收集专家" },
      { role: "user", content: `收集关于「${state.topic}」的研究数据` },
    ]);
    return {
      messages: [response],
      results: [...state.results, response.content as string],
      progress: state.progress + 25,
    };
  })
  .addNode("analyze_results", async (state) => {
    const response = await model.invoke([
      { role: "system", content: "你是一个数据分析专家" },
      { role: "user", content: `分析以下结果：\n${state.results.join("\n")}` },
    ]);
    return { messages: [response], progress: state.progress + 25 };
  })
  .addNode("write_report", async (state) => {
    const response = await model.invoke([
      { role: "system", content: "你是一个报告撰写专家" },
      { role: "user", content: `基于以下结果撰写关于「${state.topic}」的研究报告：\n${state.results.join("\n")}` },
    ]);
    return { messages: [response], progress: 100 };
  })
  // 定义边
  .addEdge(START, "plan_research")
  .addEdge("plan_research", "collect_data")
  .addEdge("collect_data", "analyze_results")
  .addEdge("analyze_results", "write_report")
  .addConditionalEdges("write_report", (state) => {
    return state.results.length === 0 ? "collect_data" : END;
  });

// 编译工作流
const researchWorkflow = workflow.compile();

// 同时创建 DeepAgent 版本（用于复杂任务派遣）
const deepResearchAgent = createDeepAgent({
  tools: [webSearchTool],
  systemPrompt: "你是一个专业的研究助手，善于搜索、分析和整理信息。",
});

// API 路由处理研究助手请求
app.post('/research', async (req, res) => {
  try {
    // 执行 LangGraph 工作流（自动被 LangSmith 追踪）
    const result = await researchWorkflow.invoke({
      messages: [],
      topic: req.body.topic,
      subtasks: [],
      progress: 0,
      results: [],
    });

    res.json({
      success: true,
      messages: result.messages,
      progress: result.progress,
      results: result.results,
    });
  } catch (error) {
    res.status(500).json({
      success: false,
      error: error.message,
    });
  }
});

// 启动服务
app.listen(port, () => {
  // eslint-disable-next-line no-console
  console.log(`研究助手服务已启动，端口：${port}`);
});

九、结论与展望

LangChain.js/LangGraph.js/DeepAgents.js/LangSmith.js技术栈完全有能力构建生产级的复杂智能体应用，但其成功部署依赖于对各组件特性的深入理解与合理组合。通过LangChain.js的基础组件、LangGraph.js的复杂工作流编排、DeepAgents.js的高级智能体抽象以及LangSmith.js的生产监控能力，开发者可以构建出功能强大且可靠的复杂Agent系统。

在构建过程中，开发者应注意以下几点：

  1. 分层设计：充分利用各组件的分层特性，避免功能重叠和代码冗余
  2. 渐进式开发：从简单工作流开始，逐步增加复杂度和代理数量
  3. 可观测性优先：在早期集成LangSmith.js的追踪功能，便于后续调试和优化
  4. 安全为本：为每个代理和工具设置明确的权限边界，确保系统安全
  5. 性能优化：针对生产环境优化记忆存储、工作流执行和代理协作机制

随着Agent技术的不断发展，这一技术栈也将持续演进。未来，我们可以期待以下改进：

  • 更强大的工作流编排能力，支持更复杂的多智能体协作模式
  • 更丰富的记忆管理选项，包括自动记忆优化和知识图谱集成
  • 更高效的生产环境部署工具，简化从开发到生产的流程
  • 更全面的Agent安全机制，包括自动权限管理和行为审计

对于TypeScript开发者而言，掌握这一技术栈将为构建下一代AI应用奠定坚实基础。通过合理组合LangChain.js、LangGraph.js、DeepAgents.js和LangSmith.js，开发者可以专注于业务逻辑的实现，而无需从零开始构建完整的Agent系统，显著提高开发效率和系统质量。

# 人工智能 # typescript
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

AtomGit 首发开源｜光轮智能发布全球首个十万小时级全模态人类行为开源数据集 EgoSuite-Open100K

avatar AtomGit开源社区
cover

AtomCode 全新上线万亿代码模型 LongCat-2.0。限时 7 天免费体验！

avatar AtomGit开源社区
cover

构筑赋能金融行业应用 Agent｜20 强决战北京，一场金融 Agent 的硬核答卷

avatar AtomGit开源社区