---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: private
status: active
tags:
  - study
  - langchain
  - reference
  - api
topic: LangChain Python API Reference 的职责与版本边界
sources:
  - https://docs.langchain.com/oss/python/reference/overview
  - https://docs.langchain.com/oss/python/reference/deepagents-python
  - https://docs.langchain.com/oss/python/reference/langchain-python
  - https://docs.langchain.com/oss/python/reference/langgraph-python
  - https://docs.langchain.com/oss/python/reference/integrations-python
last_verified: 2026-08-11
---
# API Reference 与版本边界

## 一句话结论

`docs.langchain.com` 负责概念、教程、操作方法和架构决策，`reference.langchain.com` 负责由当前包源码生成的类、函数、参数与类型清单。实现时应先用概念文档确定正确抽象，再以**已安装版本**对应的 API Reference 和类型签名落地，不能把示例代码当成永久兼容契约。

## 五个 Reference 入口

| docs 入口 | 跳转目标 | 主要用途 |
|---|---|---|
| Reference overview | Reference 总索引 | 在 Deep Agents、LangChain、LangGraph、Integrations、MCP Adapter 间导航 |
| Deep Agents Python | `reference.langchain.com/python/deepagents` | `create_deep_agent`、middleware、backend protocol、sandbox、state 等符号 |
| LangChain Python | `reference.langchain.com/python/langchain` | `create_agent`、model 初始化、middleware、structured output、HITL 等符号 |
| LangGraph Python | `reference.langchain.com/python/langgraph` | `StateGraph`、`Command`、`interrupt`、stream、runtime、checkpoint 等符号 |
| Integrations Python | `reference.langchain.com/python/integrations/overview` | provider 包、模型、向量库、工具及其他生态组件的 API 入口 |

后四个 `docs.langchain.com` 页面本质上是 307 跳转入口；完整符号页位于外部 Reference 子站。这个边界很重要：全站学习账本登记的是 docs 内部入口，具体编码时再按所用包和版本下钻到外部符号页。

## 概念文档与 API Reference 如何配合

1. **先定抽象**：在概念页确认应选 Deep Agents、LangChain agent 还是 LangGraph，以及状态、记忆、HITL、流式和安全边界。
2. **再定版本**：锁定 `pyproject.toml`、lockfile 或运行环境中的实际包版本。
3. **最后查签名**：在 API Reference 确认构造参数、同步/异步方法、返回类型、异常和弃用标记。
4. **以运行测试收口**：Reference 能说明接口，不能替代 provider 凭证、网络、持久化、并发和恢复测试。

## 生产使用原则

- 不从私有模块路径导入实现细节；优先使用文档列出的公开入口。
- 不根据最新在线 Reference 推断旧锁定版本一定具备同名能力；升级前对照 changelog、迁移指南和类型检查。
- provider integrations 独立版本化，核心包升级通过不代表每个 provider 包都兼容。
- API 清单出现类或函数，只证明符号存在；吞吐、配额、区域、数据保留和错误语义仍以 provider 文档与真实测试为准。
- Reference 内容由独立构建管线生成；符号缺失、错误链接或包未收录，应通过专用 reference docs issue 报告，而不是直接修改概念文档页面。

## 当前外部边界

本笔记精读了 `docs.langchain.com` 的五个 Reference 入口，并核对了跳转后的顶层包清单；没有把 `reference.langchain.com` 的每一个类、函数和深层锚点计入 docs 全站页面数。后续具体项目选定依赖版本时，再按实际调用面建立版本化 API 清单，避免把不断变化的生成式 Reference 全量复制进 Vault。