跳到主要内容

11-真实LangChain接入指南

核对日期：2026-05-18
官方资料：JS overview https://docs.langchain.com/oss/javascript/langchain/overview；Agents https://docs.langchain.com/oss/javascript/langchain/agents；Tools https://docs.langchain.com/oss/javascript/langchain/tools；Models https://docs.langchain.com/oss/javascript/langchain/models。

目标​

本仓库默认用离线 runtime，是为了让学习者不依赖 API Key 也能跑通工具、RAG、记忆和 eval。真实项目要把 src/core/agent-runtime.ts 替换为官方 LangChain 包和 provider 集成。本章给出迁移顺序，不让你在第一天就把所有代码改成不可调试的黑盒。

机制​

迁移分三层：

第一层只替换模型；第二层替换 tool binding 和 agent loop；第三层接 trace、checkpointer、store、HITL。这样做可以隔离变量：如果第一层就失败，问题只在 provider 配置或模型调用，不会混入 RAG 和审批逻辑。

TypeScript 接入顺序​

1. 安装官方包​

按目标 provider 选择官方集成包。示例命令要以官方文档为准：

npm install langchain @langchain/core zod
# provider 包按实际选择安装，例如 OpenAI、Anthropic、Google、Ollama 等集成。

不要在源码里写 key；使用 .env，并把 .env 加入 .gitignore。

2. 建立 model factory​

目标是把 provider 细节收敛到一个文件，业务代码只拿 chatModel。

import { z } from "zod";

const envSchema = z.object({
  LLM_PROVIDER: z.enum(["openai", "anthropic", "ollama"]),
  MODEL_NAME: z.string().min(1),
});

export function loadModelConfig(env: NodeJS.ProcessEnv) {
  return envSchema.parse(env);
}

真实 provider 初始化请按官方文档填写 import path。不要把 provider SDK 的异常直接抛给用户层，应转成统一错误。

3. 迁移 tool​

本仓库的工具形状：

tool({
  name: "search_knowledge_base",
  schema: z.object({ query: z.string() }),
  execute: async ({ query }) => search(query),
});

迁移原则：

  • schema 保持不变。
  • execute 内部继续走 Tool Gateway 或内部服务。
  • 权限检查留在业务层，不靠模型 description。
  • 工具输出继续走结构化类型，不返回 provider 原始对象。

4. 迁移 agent​

Agent 迁移时保留三类测试：

测试为什么必须保留
tool schema 失败证明模型或调用层不能绕过参数校验
权限拒绝证明真实 Agent 不会调用隐藏工具
structured output证明输出仍可被业务消费

5. 接 LangSmith​

接入 trace 后先检查脱敏：

  • prompt 是否包含用户隐私。
  • tool output 是否包含内部 URL、token、堆栈。
  • RAG 文档是否允许进入外部观测平台。
  • trace id 是否能关联业务 request id。

Python 差异​

Python 侧常见迁移路径是 create_agent、Pydantic schema、provider 包和 LangGraph checkpointer/store。TypeScript 侧常见 zod schema 和 JS provider 包。不要直接复制 Python import；只复制概念和测试用例。

工程边界​

边界推荐做法
provider key环境变量或密钥管理服务
prompt 版本文件化或配置化，进入 review
tool 权限后端 policy，不写在 prompt
eval datasetJSON/数据库版本化，CI 运行
trace脱敏后保存，设置保留周期

常见反模式​

反模式后果
一次性替换所有 mock失败时不知道是模型、工具还是 RAG 出问题
真实 key 写进 README 示例容易泄露
只在本地手动试聊换模型或 prompt 后回归不可见
把 provider 错误原样返回泄露内部实现和调试信息

验收清单​

  • 没有 .env、key、token 被提交。
  • npm test 仍通过。
  • 至少 1 个真实 provider smoke test 可手动运行。
  • 离线 eval 和真实 provider eval 结果分别记录。
  • trace 中没有敏感字段。
  • 工具权限测试没有因为接官方 Agent 失效。

练习任务​

  1. 新增 src/live/model-factory.ts，只做配置校验，不接真实 provider。
  2. 选一个 provider，按官方文档写 live smoke test，但默认不在 CI 中运行。
  3. 把企业知识库 Agent 的 answer schema 保持不变，只替换生成答案的模型调用。