学习笔记 · Obsidian
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 如何配合
- 先定抽象：在概念页确认应选 Deep Agents、LangChain agent 还是 LangGraph，以及状态、记忆、HITL、流式和安全边界。
- 再定版本：锁定
pyproject.toml、lockfile 或运行环境中的实际包版本。 - 最后查签名：在 API Reference 确认构造参数、同步/异步方法、返回类型、异常和弃用标记。
- 以运行测试收口：Reference 能说明接口，不能替代 provider 凭证、网络、持久化、并发和恢复测试。
生产使用原则
- 不从私有模块路径导入实现细节；优先使用文档列出的公开入口。
- 不根据最新在线 Reference 推断旧锁定版本一定具备同名能力；升级前对照 changelog、迁移指南和类型检查。
- provider integrations 独立版本化，核心包升级通过不代表每个 provider 包都兼容。
- API 清单出现类或函数，只证明符号存在；吞吐、配额、区域、数据保留和错误语义仍以 provider 文档与真实测试为准。
- Reference 内容由独立构建管线生成；符号缺失、错误链接或包未收录，应通过专用 reference docs issue 报告，而不是直接修改概念文档页面。
当前外部边界
本笔记精读了 docs.langchain.com 的五个 Reference 入口，并核对了跳转后的顶层包清单；没有把 reference.langchain.com 的每一个类、函数和深层锚点计入 docs 全站页面数。后续具体项目选定依赖版本时，再按实际调用面建立版本化 API 清单，避免把不断变化的生成式 Reference 全量复制进 Vault。