langchain-dev-guide

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

LangChain Dev Guide

LangChain 开发指南

A systematic summary of typical issues, non-obvious behaviors, and verified solutions encountered in real engineering with the LangChain / LangGraph ecosystem. Every entry comes from a real development scenario and is organized by category.

[!IMPORTANT] This skill is an engineering practice reference, not an introductory tutorial. Each entry assumes the developer is already familiar with basic LangChain concepts (agent, tool, message, graph).

本文系统总结了在LangChain / LangGraph生态系统实际工程中遇到的典型问题、非直观行为及已验证的解决方案。每个条目均来自真实开发场景，并按类别整理。

[!IMPORTANT] 本技能是工程实践参考，而非入门教程。每个条目都假设开发者已熟悉LangChain的基本概念（agent、tool、message、graph）。

How to Use

使用方法

First use the "Scenario Index" below to locate the category file your problem belongs to.
When unsure which category applies, search keywords directly in the "Common Issues Quick Reference".
For ContextSeek / semantic memory: start with contextseek-middleware.md to identify your scenario, then go to contextseek-params.md for specific parameter configuration issues.
Once you find the relevant section, read it in depth — every entry follows the structure Symptom → Cause → Solution → Lessons learned.

首先使用下方的「场景索引」定位问题所属的分类文件。
不确定所属分类时，直接在「常见问题快速参考」中搜索关键词。
关于ContextSeek / 语义记忆：先查看contextseek-middleware.md确定场景，再参考contextseek-params.md解决具体参数配置问题。
找到相关章节后深入阅读——每个条目均遵循症状 → 原因 → 解决方案 → 经验总结的结构。

Scenario Index

场景索引

Category	File	Trigger Scenarios
Deep Agents	reference/deepagents.md	Model selection, filesystem backend, disabling the general-purpose sub-agent, file permissions, long-term memory
OpenAI-compatible Model Integration	reference/model-integration.md	Pitfalls when using `ChatOpenAI` against OpenAI-compatible providers, integrating Reasoning models (chain-of-thought / `reasoning_content` )
CN Model Integration	reference/cn-models/README.md	Generating LangChain integration classes for Chinese providers (DeepSeek, Qwen, GLM, Moonshot)
Middleware	reference/middleware.md	Middleware execution order, `state_schema` merging, HITL `resume` values, modifying state from `wrap_model_call`
Streaming Output	reference/streaming.md	Choosing between `stream_events` and `stream` , distinguishing tokens from multiple LLMs, disabling streaming, custom progress events
Multi-Agent Orchestration	reference/multi-agent.md	subagents vs handoffs, tool-per-agent vs dispatch, retrieving subagent state, trimming subagent boilerplate, quickly building handoff setups
Other Common Issues	reference/common-issues.md	High-frequency standalone issues that don't fit the categories above. Currently includes: tools returning data to both the model and the application layer, `with_structured_output` returning None, MCP tools unable to access runtime context
ContextSeek — Use Case Scenarios	reference/contextseek-middleware.md	Agent loses context across sessions, tool call auditing, cross-topic knowledge discovery (dream), SRE provenance / confidence tracing, enterprise knowledge cold-start (DataPlug)
ContextSeek — Parameter & Config Issues	reference/contextseek-params.md	scope isolation, auto_store / record_tool_calls write volume, auto_compact throttling and shutdown, retrieval_tags / min_score filtering, tool_arg_overrides, dream trigger conditions, dream item decay, evidence_chain vs chain_confidence, DataPlug vs ctx.add(), plug() scope priority, auto_dream dual-gate triggering

分类	文件	触发场景
Deep Agents	reference/deepagents.md	模型选择、文件系统后端、禁用通用子代理、文件权限、长期记忆
兼容OpenAI的模型集成	reference/model-integration.md	使用 `ChatOpenAI` 对接兼容OpenAI的提供商时的陷阱、集成推理模型（思维链 / `reasoning_content` ）
中文模型集成	reference/cn-models/README.md	为中文提供商（DeepSeek、Qwen、GLM、Moonshot）生成LangChain集成类
中间件	reference/middleware.md	中间件执行顺序、 `state_schema` 合并、HITL `resume` 值、从 `wrap_model_call` 修改状态
流式输出	reference/streaming.md	`stream_events` 与 `stream` 的选择、区分多个LLM的token、禁用流式输出、自定义进度事件
多Agent编排	reference/multi-agent.md	子代理vs移交、按Agent分配工具vs调度、获取子代理状态、简化子代理模板代码、快速构建移交式架构
其他常见问题	reference/common-issues.md	不适合上述分类的高频独立问题。目前包括：工具同时向模型和应用层返回数据、 `with_structured_output` 返回None、MCP工具无法访问运行时上下文
ContextSeek — 使用场景	reference/contextseek-middleware.md	Agent跨会话丢失上下文、工具调用审计、跨主题知识发现（dream）、SRE来源/置信度追踪、企业知识冷启动（DataPlug）
ContextSeek — 参数与配置问题	reference/contextseek-params.md	范围隔离、auto_store / record_tool_calls写入量、auto_compact限流与关闭、retrieval_tags / min_score过滤、tool_arg_overrides、dream触发条件、dream条目衰减、evidence_chain vs chain_confidence、DataPlug vs ctx.add()、plug()范围优先级、auto_dream双门限触发

Common Issues Quick Reference

常见问题快速参考

Keyword / Error	Where to Look
Which model to choose / Deep Agent performing poorly	deepagents issue 1
Filesystem backend / local files / file permissions	deepagents issues 2 / 4
Disabling the default sub-agent / general-purpose	deepagents issue 3
Long-term memory / store	deepagents issue 5
OpenAI-compatible model / `ChatOpenAI` not working	model-integration issue 1
Reasoning model / `reasoning_content` / chain-of-thought lost	model-integration issue 2
Chinese model / CN provider / DeepSeek / Qwen / GLM / Moonshot	cn-models README
`langchain-cn-models` (embedded) / generate integration class	cn-models README
Middleware order messed up / before/after counterintuitive	middleware issue 1
`state_schema` fields not merged / input/output control	middleware issue 2
`interrupt` resume value missing / HITL	middleware issue 3
Modifying state inside `wrap_model_call` has no effect	middleware issue 4
Choosing between `astream_events` and `astream` for streaming	streaming issue 1
Distinguishing token sources across multiple LLMs	streaming issue 2
Disabling streaming for a specific model	streaming issue 3
Custom events from inside a tool not being emitted	streaming issue 4
Multi-agent: subagents vs handoffs	multi-agent issue 1
Single dispatch tool vs one tool per agent	multi-agent issue 2
`interrupt` can't see subagent state	multi-agent issue 3
Too much subagent wrapper boilerplate	multi-agent issue 4
Quickly building a handoff-based multi-agent setup	multi-agent issue 5
Tool returning data to both the model and the app layer / `artifact` / `Command(update=...)`	common-issues issue 1
`with_structured_output` returning None / missing fields	common-issues issue 2
MCP tool can't access `user_id` / `store` / state / API key	common-issues issue 3
Agent loses context across sessions — personal assistant or support bot	contextseek-middleware issue 1
Multi-tool data-pipeline agent — auditing tool call decisions	contextseek-middleware issue 2
Research agent accumulates raw notes — cross-topic pattern discovery	contextseek-middleware issue 3
SRE incident postmortem agent — tracing knowledge confidence and conflicts	contextseek-middleware issue 4
Enterprise knowledge migration — agent is retrieval-ready on day one	contextseek-middleware issue 5

关键词 / 错误	查看位置
模型选择 / Deep Agent表现不佳	deepagents 问题1
文件系统后端 / 本地文件 / 文件权限	deepagents 问题2 / 4
禁用默认子代理 / 通用代理	deepagents 问题3
长期记忆 / store	deepagents 问题5
兼容OpenAI的模型 / `ChatOpenAI` 无法工作	model-integration 问题1
推理模型 / `reasoning_content` / 思维链丢失	model-integration 问题2
中文模型 / 中文提供商 / DeepSeek / Qwen / GLM / Moonshot	cn-models README
`langchain-cn-models` （嵌入式）/ 生成集成类	cn-models README
中间件顺序混乱 / before/after不符合直觉	middleware 问题1
`state_schema` 字段未合并 / 输入输出控制	middleware 问题2
`interrupt` resume值缺失 / HITL	middleware 问题3
在 `wrap_model_call` 内修改状态无效果	middleware 问题4
流式输出选择 `astream_events` 还是 `astream`	streaming 问题1
区分多个LLM的token来源	streaming 问题2
为特定模型禁用流式输出	streaming 问题3
工具内的自定义事件未触发	streaming 问题4
多Agent：子代理vs移交	multi-agent 问题1
单调度工具vs每个Agent一个工具	multi-agent 问题2
`interrupt` 无法查看子代理状态	multi-agent 问题3
子代理模板代码冗余过多	multi-agent 问题4
快速构建基于移交的多Agent架构	multi-agent 问题5
工具同时向模型和应用层返回数据 / `artifact` / `Command(update=...)`	common-issues 问题1
`with_structured_output` 返回None / 字段缺失	common-issues 问题2
MCP工具无法访问 `user_id` / `store` / 状态 / API密钥	common-issues 问题3
Agent跨会话丢失上下文 — 个人助手或客服机器人	contextseek-middleware 问题1
多工具数据流水线Agent — 审计工具调用决策	contextseek-middleware 问题2
研究Agent积累原始笔记 — 跨主题模式发现	contextseek-middleware 问题3
SRE事件复盘Agent — 追踪知识置信度与冲突	contextseek-middleware 问题4
企业知识迁移 — Agent首日即可就绪进行检索	contextseek-middleware 问题5