LangChain Dev Guide
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).
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.
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, long SKILL.md truncated by read_file 100-line default |
| Structured Output | reference/structured-output.md | Model-level method selection, create_agent strategies, missing fields, unsupported tool_choice, provider-side 400 errors on forced schema tool selection |
| 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, MCP tools unable to access runtime context, invalid_tool_calls, and dynamic system prompt placeholders |
| 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 |
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 |
SKILL.md truncated / only first 100 lines read / read_file limit / progressive disclosure | deepagents issue 6 |
with_structured_output returning None / missing fields | structured-output issue 1 |
create_agent / response_format / ProviderStrategy / ToolStrategy | structured-output issue 1 |
with_structured_output / function_calling / tool_choice unsupported / deepseek-reasoner does not support this tool_choice | structured-output issue 2 |
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 |
MCP tool can't access user_id / store / state / API key | common-issues issue 2 |
invalid_tool_calls / tool never executes / malformed tool-call JSON | common-issues issue 3 |
Dynamic system prompt placeholders / format_prompt / Jinja2 prompt variables | common-issues issue 4 |
| 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 |