学习笔记 · Obsidian
LangChain TypeScript：定位、安装与 Python 对照
一句话结论
LangChain 1.x 的 TypeScript 版本和 Python 版本共享同一个心智模型：
Agent = Model + Harness
模型负责推理，harness 负责消息、工具、状态、中间件、持久化和执行循环。TypeScript 的高层入口是 createAgent，底层同样运行在 LangGraph 上。它不是 Python 版的逐字符翻译：包名、字段命名、schema、类型推断、流式接口、前端 SDK 和部分能力边界都不同，复制 Python 示例后机械改成驼峰通常不可靠。
选择哪一层
| 层级 | 适合场景 | TypeScript 侧关注点 |
|---|---|---|
| Deep Agents | 长任务、研究/编码、需要规划、文件、压缩和 subagent | deepagents 有自己的版本节奏；文件与执行必须放进受控 backend/sandbox |
LangChain createAgent | 自己组合模型、工具、prompt、middleware | 默认推荐起点；返回可调用、可流式的 compiled graph |
| LangGraph | 显式状态机、确定性分支、复杂恢复与编排 | StateSchema、channel/reducer、checkpoint 和 node 需要自行设计 |
优先从单个 createAgent 开始。只有当上下文隔离、并行、权限或团队边界产生明确收益时，再引入 multi-agent；只有高层 loop 无法表达流程时，再下沉 LangGraph。
安装与运行时边界
langchain和@langchain/core当前要求 Node.js 22+；文档同时列出 Bun 1.0+。- 可使用 npm、pnpm、Yarn 或 Bun，但仓库应锁定一种包管理器及 lockfile，CI 与生产保持一致。
- provider 独立分包，例如
@langchain/openai、@langchain/anthropic；核心包不会带齐所有模型与向量库。 - 最小安装通常是
langchain @langchain/core加一个 provider 包。LangGraph、MCP、Deep Agents、前端 SDK 按能力单独引入。 - API key 从环境或 secret manager 注入；浏览器端不得持有模型、LangSmith 或 MCP 服务端密钥。
最小调用链是：Zod 定义工具输入 → tool(...) → createAgent({ model, tools, systemPrompt }) → agent.invoke({ messages })。需要稳定类型时，不要把结果降级为 any，应让 createAgent、state schema 与 useStream 的泛型贯穿端到端。
组件架构
LangChain 把 agent 应用拆成可独立替换的组件：
- loader 产生
Document，其正文属性是pageContent； - splitter 生成可检索 chunk；
- embedding 与 vector store 建索引；
- retriever 按查询返回相关文档；
- model 生成内容并提出 tool calls；
- tools 接入数据库、API、代码执行和业务动作；
- agent 循环协调 model/tool；
- checkpointer、store、middleware 处理短期状态、长期记忆、安全和可靠性。
固定 2-step RAG、可自主调用检索工具的 agent、supervisor + specialists 都是这些组件的不同组合，不是三套互不兼容的框架。
TypeScript 与 Python 的关键对照
| 主题 | TypeScript / JavaScript | Python |
|---|---|---|
| 运行时 | Node.js 22+；Bun 1.0+ | Python 3.10+ |
| Agent 工厂 | createAgent | create_agent |
| Prompt 参数 | systemPrompt | system_prompt |
| Structured output | responseFormat，结果 structuredResponse | response_format，结果 structured_response |
| Schema | Zod、Standard Schema、JSON Schema | Pydantic、dataclass、TypedDict、JSON Schema |
| Context/state | contextSchema、stateSchema、StateSchema | context_schema、state_schema |
| 持久线程 | configurable: { thread_id } | 同一协议，但 Python 调用外层参数写法不同 |
| 异步 | Promise、async iterator；普通方法名通常不加 a | sync/async 常成对，如 invoke/ainvoke |
| 前端 | 官方 React/Vue/Svelte/Angular SDK，类型可从 agent 推断 | 后端通常手写前端状态/事件类型 |
需要特别警惕“混合命名”：TypeScript 公开配置通常是 camelCase，但消息协议为了兼容 provider/序列化仍有 tool_calls、tool_call_id；内容块 getter 是 contentBlocks，ToolRuntime 又使用 toolCallId。是否驼峰不能凭直觉判断，应以当前 JavaScript API Reference、类型检查器和运行时测试为准。
设计哲学与版本语义
LangChain 的稳定方向是统一 provider 接口、让模型通过工具行动，并把持久执行、流式、HITL 和观测放进 agent harness。v1 将早期大量 chains/agents 收敛为一个 LangGraph-backed agent；旧 v0.x 能力迁到 @langchain/classic。维护旧系统可以暂时保留 classic，新代码不应继续扩大 classic 依赖面。
文档是滚动更新的，不是固定版本手册。当前页面同时可见不同发布阶段的导入方式（langchain 与 @langchain/agents）、Python 风格术语和未来模型名。实践中应同时固定：
langchain、@langchain/core、@langchain/langgraph、deepagents和 provider 的直接版本；- 当前版本的 JavaScript API Reference；
- TypeScript 编译和契约测试；
- 升级前后的 trace/eval 基线。
逐页覆盖
| 页面 | 学习结论 |
|---|---|
| Overview | createAgent 是主要高层 harness；能力来自标准模型接口与 LangGraph runtime。 |
| Install | Node.js 22+、Bun 1.0+；核心和 provider 分包安装。 |
| Quickstart | 从模型、Zod 工具、agent loop 到 LangSmith trace 的最短路径。 |
| Philosophy | 降低 agent 起步成本，同时保留 provider 可替换和生产控制。 |
| Component architecture | loader、splitter、embedding、store、retriever、model、tool、agent、memory 的连接关系。 |
| Academy | 该 URL 当前跳出 docs，重定向到外部 LangChain Academy 课程站；它是课程入口，不是可抓取的本栏 Markdown 教材。 |
无尾路径 /oss/javascript/langchain 是页面内可点击入口，当前 307 到 overview；它不增加新的正文知识，但计入路由闭包。
实践检查清单
- ○ Node、包管理器、direct dependencies 和 provider 版本已锁定。
- ○ 新项目先用一个 agent 和少量高质量工具验证闭环。
- ○ schema 既有 TypeScript 类型，又有运行时校验；不依赖
as绕过验证。 - ○ 凭证只在受控服务端；浏览器只连接经过鉴权的 agent endpoint。
- ○ 用 trace、集成测试和 eval 证明可靠性，不以一次 demo 成功替代上线验证。