17-官方核心组件全景
核对日期：2026-05-18
官方资料：LangChain JS overview https://docs.langchain.com/oss/javascript/langchain/overview；Agents https://docs.langchain.com/oss/javascript/langchain/agents；Models https://docs.langchain.com/oss/javascript/langchain/models；Tools https://docs.langchain.com/oss/javascript/langchain/tools；Structured output https://docs.langchain.com/oss/javascript/langchain/structured-output。
官方概念
LangChain v1 的 TypeScript 文档把能力分成四层：
| 层级 | 官方页面 | 作用 |
|---|---|---|
| Get started | Install、Quickstart、Changelog、Philosophy | 安装、快速起步和版本变化 |
| Core components | Agents、Models、Messages、Tools、Short-term memory、Event streaming、Streaming、Structured output | 构建 LLM 应用和 Agent 的基础组件 |
| Middleware | Overview、Prebuilt middleware、Custom middleware | 在模型调用、工具调用和 Agent 生命周期中插入控制逻辑 |
| Advanced usage | Guardrails、Runtime、Context engineering、MCP、HITL、Multi-agent、Retrieval、Long-term memory | 生产可靠性、上下文、外部工具、审批、知识和长期状态 |
官方 overview 的核心判断是：LangChain 提供预构建 Agent 架构和模型/工具集成；Agent 架构建立在 LangGraph 之上；观测、调试和评估应接 LangSmith。
机制
从工程角度看，LangChain 不是一个单一 API，而是一组可组合的边界：
这个图里最容易被忽略的是 middleware 和 runtime context。官方高阶文档大量围绕它们展开，因为 Agent 的可靠性问题通常不是“模型完全不会”，而是“模型没有得到正确上下文、正确工具、正确输出约束和正确安全边界”。
TypeScript 官方模块速查
| 官方能力 | TypeScript 关键入口 | 什么时候用 |
|---|---|---|
| Agent | createAgent | 需要模型循环调用工具、处理多步任务 |
| Model | initChatModel 或 provider class | 单次生成、分类、抽取，或作为 Agent 推理引擎 |
| Messages | role/content/message objects | 管理 system/user/assistant/tool 历史 |
| Tools | tool + zod schema | 让模型调用外部 API、数据库、检索器 |
| Structured output | responseFormat、providerStrategy、toolStrategy | 输出要被程序稳定消费 |
| Short-term memory | checkpointer、thread id | 同一会话跨轮状态 |
| Long-term memory | LangGraph store、namespace/key | 跨会话用户画像、偏好、历史 |
| Runtime | contextSchema、runtime.context | 把 user id、权限、连接、配置传给工具和 middleware |
| Middleware | createMiddleware | 动态模型、动态工具、prompt 注入、日志、错误处理 |
| Streaming | streamMode | 进度、token、custom updates |
| Guardrails | PII、HITL、自定义 middleware | 安全、合规、内容过滤 |
官方组件之间的关系
| 组合 | 典型用途 | 关键风险 |
|---|---|---|
| Model + Structured output | 抽取、分类、表单生成 | provider 支持差异、schema 失败 |
| Agent + Tools | 任务执行、工具调用 | 工具误调用、权限绕过 |
| Agent + Middleware | 动态模型、动态工具、安全拦截 | 隐式逻辑过多，难复现 |
| Agent + Memory | 多轮任务、续写上下文 | stale context、隐私写入 |
| Retrieval + Structured output | 可引用问答 | citation 编造、低召回胡答 |
| Runtime + Tools | 按用户/租户/环境执行工具 | runtime context 泄露到 prompt |
| HITL + Checkpointer | 高风险动作审批 | 没有持久化就无法安全暂停/恢复 |
Python 差异
Python 文档通常用 create_agent、Pydantic/TypedDict、LangGraph checkpointer/store；TypeScript 文档使用 createAgent、zod、JS provider 包和 contextSchema。概念层可对齐，代码层必须回到对应语言文档核对。
工程边界
- LangChain 的 Agent 能帮你组织模型、工具、状态和 middleware，但不会替你完成权限、安全、数据治理和 eval。
- LangChain Agent 建在 LangGraph 上；当你需要复杂状态机、强恢复、多分支审批时，应直接理解 LangGraph。
- LangSmith 是观测和 eval 工具，不是质量本身；质量来自数据集、断言、trace 和回归流程。
常见反模式
| 反模式 | 为什么错 |
|---|---|
只学 createAgent | 忽略 model、messages、tool schema、middleware、memory 和 eval |
| 把高级用法都写进 prompt | prompt 不是权限系统，也不是可审计工作流 |
| 混用官方概念和自研概念但不做映射 | 后续接官方包时会出现接口错位 |
| 不保存官方核对日期 | LangChain 文档和 API 迭代快，旧示例会误导实现 |
练习任务
- 用本章表格给当前三个项目标注用到了哪些官方组件。
- 选择一个项目，画出 messages、tools、runtime context、middleware 和 eval 的数据流。
- 找出当前离线 runtime 与官方
createAgent的差异，写到项目 README 的“迁移风险”中。