---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: private
status: active
tags:
  - study
  - langchain
  - typescript
  - javascript
  - architecture
topic: LangChain TypeScript 定位、安装、版本与 Python 对照
sources:
  - https://docs.langchain.com/oss/javascript/langchain
  - https://docs.langchain.com/oss/javascript/langchain/academy.md
  - https://docs.langchain.com/oss/javascript/langchain/component-architecture.md
  - https://docs.langchain.com/oss/javascript/langchain/install.md
  - https://docs.langchain.com/oss/javascript/langchain/overview.md
  - https://docs.langchain.com/oss/javascript/langchain/philosophy.md
  - https://docs.langchain.com/oss/javascript/langchain/quickstart.md
last_verified: 2026-08-11
---
# 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 应用拆成可独立替换的组件：

1. loader 产生 `Document`，其正文属性是 `pageContent`；
2. splitter 生成可检索 chunk；
3. embedding 与 vector store 建索引；
4. retriever 按查询返回相关文档；
5. model 生成内容并提出 tool calls；
6. tools 接入数据库、API、代码执行和业务动作；
7. agent 循环协调 model/tool；
8. 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 成功替代上线验证。

## 延伸

- [[02-TypeScript-Agent-Model-Message-and-Tools]]
- [[04-TypeScript-Middleware-Context-Runtime-and-HITL]]
- [Python 对照](../Python/01-Overview-and-Setup.md)