09-Python-API差异速查
核对日期：2026-05-18
官方资料：Python overview https://docs.langchain.com/oss/python/langchain/overview；JS overview https://docs.langchain.com/oss/javascript/langchain/overview。
官方概念
LangChain v1 的概念层在 Python 和 TypeScript 中基本一致：model、messages、tools、agent、structured output、memory、retrieval、middleware、runtime。差异主要来自语言生态、类型系统、provider 包和 schema 工具。
机制
同一能力的迁移方式：
| 能力 | TypeScript 常见形态 | Python 常见形态 |
|---|---|---|
| Agent | createAgent / JS 官方 API | create_agent |
| Tool schema | zod | Pydantic / TypedDict / function signature |
| Runtime config | object / context | dict / runtime context |
| Memory | checkpointer/store 概念 | checkpointer/store 概念 |
| Eval | LangSmith JS SDK 或自建 runner | LangSmith Python SDK 或自建 runner |
TypeScript 写法
本手册优先用 TypeScript 实现，因为综合项目更容易接入前端、Node API 和全栈服务。核心要求是严格类型、schema 校验、测试和 eval。
Python 差异
不要做机械翻译：
- Python 的
snake_case不等于 TypeScript 的 API 名称。 - Python 的 Pydantic schema 不等于 TypeScript 的
zodschema。 - provider 集成包和版本节奏可能不同。
- 官方示例中的模型名称要按当前 provider 文档核对。
工程边界
- 团队混合语言时，应统一业务 schema、eval dataset 和 trace 字段。
- 不同语言实现必须通过同一组回归用例验收。
- 语言差异不应改变权限、安全和审计策略。
常见反模式
| 反模式 | 后果 |
|---|---|
| 复制 Python 示例到 TS | import、schema、runtime 都可能错 |
| 只测一个语言实现 | 双栈行为不一致 |
| 忽略 provider 包差异 | 模型能力和工具调用格式不一致 |
练习任务
- 选择一个 example，写出 Python 概念等价伪代码。
- 列出哪些字段必须在 TS/Python 双栈中保持一致。
- 给项目 eval 增加一个跨语言共享 JSON case 的设计。