langchain-dev-guide

LangChain 开发指南

系统总结 LangChain / LangGraph 生态中真实工程实践遇到的典型问题、不明显的行为和经过验证的解决方案。每个条目都来自真实开发场景，并按类别整理。

重要

本技能是一份工程实践参考，而非入门教程。每个条目都假设开发者已熟悉 LangChain 基本概念（Agent、工具、消息、图）。

使用方法

1. 首先使用下方的“场景索引”，找到问题所属类别对应的文件。
2. 不确定适用哪个类别时，直接在“常见问题速查”中搜索关键词。
3. 对于 ContextSeek / 语义记忆：先查看 contextseek-middleware.md，确定所属场景；然后查看 contextseek-params.md，了解具体参数配置问题。
4. 找到相关部分后，请仔细阅读——每个条目都遵循 症状 → 原因 → 解决方案 → 经验总结 的结构。

场景索引

类别	文件	适用场景
Deep Agents	reference/deepagents.md	模型选择、文件系统后端、禁用通用子 Agent、文件权限、长期记忆、read_file 默认读取 100 行导致长 SKILL.md 被截断
结构化输出	reference/structured-output.md	模型级方法选择、create_agent 策略、字段缺失、不支持的 tool_choice、强制选择架构工具时提供商端返回 400 错误
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 的令牌、禁用流式输出、自定义进度事件
多 Agent 编排	reference/multi-agent.md	子 Agent 与交接、每个 Agent 配置工具与分发、获取子 Agent 状态、精简子 Agent 样板内容、快速构建交接配置
其他常见问题	reference/common-issues.md	不适用于上述类别的高频独立问题。目前包括：工具同时向模型和应用层返回数据、MCP 工具无法访问运行时上下文、invalid_tool_calls 和动态系统提示词占位符
ContextSeek — 使用场景	reference/contextseek-middleware.md	Agent 跨会话丢失上下文、工具调用审计、跨主题知识发现（dream）、SRE 来源 / 置信度追踪、企业知识冷启动（DataPlug）
ContextSeek — 参数与配置问题	reference/contextseek-params.md	scope 隔离、auto_store / record_tool_calls 写入量、auto_compact 节流与关闭、retrieval_tags / min_score 筛选、tool_arg_overrides、dream 触发条件、dream 条目衰减、evidence_chain 与 chain_confidence、DataPlug 与 ctx.add()、plug() scope 优先级、auto_dream 双重门控触发

常见问题速查

关键词／错误	查看位置
选择哪个模型／Deep Agent 表现不佳	deepagents 问题 1
文件系统后端／本地文件／文件权限	deepagents 问题 2／4
禁用默认子 Agent／general-purpose	deepagents 问题 3
长期记忆／store	deepagents 问题 5
SKILL.md 被截断／只读取前 100 行／read_file 限制／渐进式披露	deepagents 问题 6
with_structured_output 返回 None／缺少字段	structured-output 问题 1
create_agent／response_format／ProviderStrategy／ToolStrategy	structured-output 问题 1
不支持 with_structured_output／function_calling／tool_choice／deepseek-reasoner does not support this tool_choice	structured-output 问题 2
OpenAI 兼容模型／ChatOpenAI 无法正常工作	model-integration 问题 1
推理模型／reasoning_content／思维链丢失	model-integration 问题 2
中文模型／中国供应商／DeepSeek／Qwen／GLM／Moonshot	cn-models README
langchain-cn-models（内嵌）／生成集成类	cn-models README
中间件顺序混乱／执行前后顺序违反直觉	middleware 问题 1
未合并 state_schema 字段／输入输出控制	middleware 问题 2
interrupt 恢复值缺失／HITL	middleware 问题 3
在 wrap_model_call 中修改状态无效	middleware 问题 4
流式传输时如何选择 astream_events 或 astream	streaming 问题 1
区分多个 LLM 的 Token 来源	streaming 问题 2
禁用特定模型的流式传输	streaming 问题 3
未发出工具内部的自定义事件	streaming 问题 4
多 Agent：子 Agent 与交接	multi-agent 问题 1
使用单个调度工具还是每个 Agent 各用一个工具	multi-agent 问题 2
interrupt 无法查看子 Agent 状态	multi-agent 问题 3
子 Agent 封装样板代码过多	multi-agent 问题 4
快速构建基于交接的多 Agent 配置	multi-agent 问题 5
工具同时向模型和应用层返回数据／artifact／Command(update=...)	common-issues 问题 1
MCP 工具无法访问 user_id／store／状态／API 密钥	common-issues 问题 2
invalid_tool_calls／工具始终不执行／格式错误的工具调用 JSON	common-issues 问题 3
动态系统提示词占位符／format_prompt／Jinja2 提示词变量	common-issues 问题 4
Agent 在不同会话间丢失上下文——个人助手或客服机器人	contextseek-middleware 问题 1
多工具数据管道 Agent——审计工具调用决策	contextseek-middleware 问题 2
研究 Agent 积累原始笔记——发现跨主题模式	contextseek-middleware 问题 3
SRE 事故复盘 Agent——追踪知识置信度与冲突	contextseek-middleware 问题 4
企业知识迁移——让 Agent 从第一天起即可检索	contextseek-middleware 问题 5