产品层级、Context 与 Memory

三层技术栈

层级	LangChain 代表	核心责任	何时使用
Framework	LangChain	model/tool/message、agent loop、middleware 等高层抽象	快速构建标准 agent，保留扩展能力
Runtime	LangGraph	durable execution、state、checkpoint、stream、HITL、低层编排	长运行、复杂状态、确定性与 agentic 混合流程
Harness	Deep Agents	planning、filesystem、subagents、context compression、预置工具	多步骤长任务，需要 batteries-included 工作台

三者可以叠加：LangChain agent 运行在 LangGraph 上，Deep Agents 又组合 LangChain/LangGraph 能力。应从满足需求的最高层开始；只有抽象不够时才向下展开，避免同时维护重复的 loop、state 和 persistence。

Python 与 TypeScript 的 /concepts/products 正文相同；TypeScript 还保留一个 /concepts 别名。它们是架构选择页，不是三个互斥产品的营销对比。

Context 的两个维度

Context 按可变性分 static/dynamic，按生命周期分 single-run/cross-conversation：

类型	载体	生命周期	示例
static runtime context	Python runtime context / TS config	单次 run，只读	user metadata、数据库连接、配置、依赖
dynamic runtime context	graph state	单次 run，可变；有 checkpointer 时可跨 invocation 恢复	messages、中间结果、工具观测
dynamic cross-conversation	store + namespace	多线程/多会话	用户画像、偏好、历史事实

runtime context 不是 LLM prompt，也不是 model context window；它是应用代码安全传递依赖和元数据的方式。只有经过 prompt/middleware/tool 选择的信息才进入模型上下文。不要用进程全局变量承载用户、tenant 或请求状态。

Short-term 与 long-term memory

短期记忆属于 thread state，经 checkpointer 保存；每个 step 开始读、执行后更新。
长期记忆属于 store，自定义 namespace，不受单一 thread ID 限制。
长对话即使没有超过 context window，也会增加成本、延迟和注意力稀释；应 trim、delete、summarize 或把稳定事实迁到 store。

长期记忆可分：semantic facts、episodic experiences、procedural instructions。写入策略有两类：hot path 立即可见但增加延迟和 agent 负担；background 降低主路径延迟但存在新鲜度、调度和重复处理问题。两者都必须有权限、租户隔离、纠错/删除和来源证据。

Provider 与 model

LangChain 用统一 model 接口降低应用层耦合，但每个 provider 仍由独立 integration package 负责版本与特性。provider:model 可自动解析包；新 model name 通常直接透传 provider API，但前提是当前包支持所需 API 版本。

Router/gateway 可以统一凭证、计费、fallback 和负载均衡，却增加一个数据与可用性中间层。OpenAI-compatible endpoint 只保证标准字段；ChatOpenAI 不会自动保留第三方非标准响应字段，需专用 integration 才能可靠使用 provider 特性。

错误索引的意义

Python 与 TypeScript 的 common errors 页是代码到排障文档的入口，异常包含 lc_error_code。主要分两组：

LangChain：prompt input、tool result 对齐、message coercion、model auth/not found/rate limit、output parsing；
LangGraph：recursion limit、chat history、concurrent update、node return value、missing checkpointer、multiple subgraphs。

错误码应进入结构化日志和告警维度，但不能回显凭证、完整 prompt 或用户隐私。具体原因与修复以各错误页为准，聚合页只负责路由。