# guage-langchain-learn

**Repository Path**: yangdechao_admin/guage-langchain-learn

## Basic Information

- **Project Name**: guage-langchain-learn
- **Description**: 基于 LangChain v1 / LangGraph v1（2025 年 10 月发布的 1.0 稳定版）的系统学习工程， 覆盖从模型调用到 Agent、RAG、流式、状态图的完整知识链路。 所有示例统一接入 DeepSeek 大模型（OpenAI 兼容协议）。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-03
- **Last Updated**: 2026-10-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# guage-langchain-learn

基于 **LangChain v1 / LangGraph v1 / LangSmith / deep-agents**（2025 年 10 月发布的 1.0 稳定版）的系统学习工程，
覆盖从模型调用到 Agent、RAG、流式、状态图的完整知识链路，
并深入 **LangGraph 高级特性**（并行/Send/子图/多 Agent/持久化/时间旅行/函数式 API）、
**LangSmith 可观测性**（追踪/评估/Prompt Hub）与 **deep-agents 深度代理**
（虚拟文件系统/子代理/记忆/人机协同）。
所有示例统一接入 **DeepSeek** 大模型（OpenAI 兼容协议）。

## 一、环境要求

| 项目 | 要求 |
| --- | --- |
| Python | >= 3.10（LangChain v1 已放弃 3.9，推荐 3.12） |
| 依赖 | 见 `requirements.txt`（langchain>=1.0、langgraph>=1.0、langsmith、deepagents 等） |
| 模型 | DeepSeek（`https://api.deepseek.com`，默认 `deepseek-flash`） |
| LangSmith | 可选：`smith.langchain.com` 免费注册后填 `.env` 的 `LANGSMITH_API_KEY` |

## 二、快速开始

```bash
# 1. 创建虚拟环境（PyCharm 打开项目后会自动识别 .venv）
python -m venv .venv

# Windows 激活
.venv\Scripts\activate
# macOS / Linux 激活
source .venv/bin/activate

# 2. 安装依赖
pip install -r requirements.txt
## 按照失败可以执行下面命令
pip install -r requirements.txt --timeout 120 --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/
pip install -r requirements.txt --timeout 120 --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple

# 3. 配置密钥：复制 .env.example 为 .env，填入你的 DeepSeek API Key
#    DEEPSEEK_BASE_URL=https://api.deepseek.com
#    DEEPSEEK_MODEL=deepseek-flash
#    DEEPSEEK_API_KEY=sk-xxxx

# 4. 运行离线单元测试（不消耗 API 额度）
pytest tests/ -v

# 5. 运行全部章节示例（会真实调用 DeepSeek API）
python run_all.py            # 全部章节
python run_all.py ch06       # 只跑第 6 章（Agent）
python run_all.py lg05       # 只跑 LangGraph 第 5 章（多 Agent）
python run_all.py da06       # 只跑 deep-agents 第 6 章（深度研究助理，耗时较长）
python run_all.py ls04       # 只跑 LangSmith 第 4 章（评估，需配置 Key）

# 也可以单独运行某个示例（在项目根目录执行）
python -m langchain_learn.ch06_agents.demo_create_agent
python -m langgraph_learn.lg05_multi_agent.demo_supervisor
python -m langsmith_learn.ls01_tracing_basics.demo_tracing_context
python -m deepagents_learn.da06_practice.demo_research_assistant
```

## 三、工程结构

```
guage-langchain-learn/
├── README.md                       # 本文件
├── requirements.txt / pyproject.toml
├── .env / .env.example             # DeepSeek 密钥配置（.env 不入库）
├── run_all.py                      # 一键运行全部示例
├── tests/
│   ├── test_offline.py             # 离线单元测试（Fake 模型，不调 API）
│   ├── test_langgraph_offline.py   # LangGraph 深入模块离线测试
│   ├── test_langsmith_offline.py   # LangSmith 模块离线测试（无 Key 场景）
│   └── test_deepagents_offline.py  # deep-agents 模块离线测试
└── langchain_learn/                # 主包，按知识点分章节
    ├── common/                     # 公共模块：配置、模型工厂、嵌入工厂
    │   ├── settings.py             #   .env 加载与配置对象（含 LangSmith 可选配置）
    │   ├── llm.py                  #   get_chat_model() 聊天模型；get_structured_model() 结构化输出
    │   └── embeddings.py           #   get_embeddings()：演示用嵌入
    ├── ch01_models/                # 第 1 章：模型调用
    ├── ch02_prompts/               # 第 2 章：Prompt 模板
    ├── ch03_output_parsers/        # 第 3 章：输出解析与结构化输出
    ├── ch04_lcel_chains/           # 第 4 章：LCEL 链式编排
    ├── ch05_tools/                 # 第 5 章：自定义工具与 Tool Calling
    ├── ch06_agents/                # 第 6 章：create_agent（v1 核心）
    ├── ch07_memory/                # 第 7 章：消息裁剪与 Agent 记忆
    ├── ch08_rag/                   # 第 8 章：RAG 检索增强生成
    ├── ch09_streaming/             # 第 9 章：流式输出与事件流
    ├── ch10_langgraph/             # 第 10 章：LangGraph 状态图与人机协同（入门）
    └── ch11_practice/              # 第 11 章：综合实战——智能客服（工具+RAG+记忆+流式）

langgraph_learn/                    # LangGraph 深入模块（承接第 10 章，lg 前缀）
├── lg01_graph_basics/              #   图解剖：拓扑/mermaid/get_state 调试
├── lg02_state_management/          #   reducer 合并策略；input/output schema；configurable 上下文
├── lg03_parallelism/               #   静态 fan-out/fan-in；Send 动态 map-reduce
├── lg04_subgraphs/                 #   子图复用与状态映射
├── lg05_multi_agent/               #   supervisor 监督者；handoff 交接（真实 API）
├── lg06_hitl_deep/                 #   Command(goto/update)；双重 interrupt 审批
├── lg07_persistence/               #   SqliteSaver；时间旅行（回放/分叉）
├── lg08_streaming_deep/            #   自定义流事件；子图流 subgraphs=True
├── lg09_functional_api/            #   @entrypoint/@task 函数式建图（真实 API）
└── lg10_patterns/                  #   orchestrator-worker；evaluator-optimizer（真实 API）

langsmith_learn/                    # LangSmith 可观测模块（ls 前缀，需 LANGSMITH_API_KEY）
├── common.py                       #   Key 检查与 Client 工厂（无 Key 自动跳过）
├── ls01_tracing_basics/            #   tracing_context 精确控制追踪范围
├── ls02_traceable/                 #   @traceable 嵌套追踪/脱敏/run_id
├── ls03_client_api/                #   Client 查询 run、还原 trace 树
├── ls04_datasets_evaluation/       #   Dataset 测试集；evaluate 评估与 LLM 裁判
├── ls05_prompt_hub/                #   Prompt Hub 版本化管理
└── ls06_langgraph_observability/   #   LangGraph×LangSmith 观测与反馈闭环

deepagents_learn/                   # deep-agents 深度代理模块（da 前缀）
├── da01_quickstart/                #   create_deep_agent 入门；默认中间件栈
├── da02_filesystem/                #   8 个文件工具与上下文工程；存储后端 Backends
├── da03_subagents/                 #   task 工具与自定义 SubAgent 委派
├── da04_customization/             #   自定义中间件/状态/AGENTS.md 记忆/skills
├── da05_hitl/                      #   interrupt_on 人工审批与文件权限
└── da06_practice/                  #   综合实战：深度研究助理（Deep Research 缩影）
```

## 四、章节知识点与学习路线

建议**按章节顺序学习**，后续章节依赖前面的概念。

### 第 1 章 ch01_models —— 模型调用基础
| 脚本 | 知识点 |
| --- | --- |
| `demo_invoke.py` | Runnable 统一接口：`invoke / stream / batch / ainvoke`；`usage_metadata` token 统计 |
| `demo_messages.py` | 消息体系 `SystemMessage / HumanMessage / AIMessage`；`(role, content)` 元组简写；多轮对话手动拼接；v1 标准内容块 `content_blocks` |

### 第 2 章 ch02_prompts —— Prompt 模板
| 脚本 | 知识点 |
| --- | --- |
| `demo_prompt_template.py` | `PromptTemplate` 与 `ChatPromptTemplate`；`MessagesPlaceholder` 嵌入对话历史；`partial` 预填充派生模板 |
| `demo_few_shot.py` | `FewShotChatMessagePromptTemplate` 用少量示例约束输出格式 |

### 第 3 章 ch03_output_parsers —— 输出解析与结构化输出
| 脚本 | 知识点 |
| --- | --- |
| `demo_parsers.py` | `StrOutputParser`、`JsonOutputParser` |
| `demo_structured_output.py` | 两条路线对比：`PydanticOutputParser`（提示词注入）vs `with_structured_output`（模型原生能力，v1 推荐） |

### 第 4 章 ch04_lcel_chains —— LCEL 链式编排
| 脚本 | 知识点 |
| --- | --- |
| `demo_pipe_chain.py` | `prompt \| model \| parser` 管道语法；`RunnableLambda` 包装自定义函数；链的流式输出 |
| `demo_runnable_advanced.py` | `RunnableParallel` 并行；`RunnableBranch` 条件路由；`with_fallbacks` 容错降级 |

### 第 5 章 ch05_tools —— 工具与 Tool Calling
| 脚本 | 知识点 |
| --- | --- |
| `demo_custom_tools.py` | `@tool` 装饰器；docstring 如何影响模型决策；工具元数据（name / description / args schema） |
| `demo_tool_calling.py` | `bind_tools`；手写"模型决策 -> 执行工具 -> 回传 ToolMessage -> 再决策"完整闭环——理解 Agent 的底层原理 |

### 第 6 章 ch06_agents —— create_agent（v1 核心，重点）
| 脚本 | 知识点 |
| --- | --- |
| `demo_create_agent.py` | `create_agent(model, tools, system_prompt)`；输入输出均为 `{"messages": [...]}`；观察决策轨迹 |
| `demo_agent_advanced.py` | `ToolStrategy` 结构化输出（`result["structured_response"]`）；`state_schema` 自定义状态（**v1 只支持 TypedDict**） |
| `demo_middleware.py` | v1 中间件机制：`AgentMiddleware` 的 `before_model / after_model` 钩子；`@dynamic_prompt` 动态系统提示；`context` 运行时上下文注入 |

> v1 变化提示：`create_agent` 取代了旧版 `langgraph.prebuilt.create_react_agent`；
> `LLMChain`、`AgentExecutor` 等旧 API 已迁移到 `langchain-classic` 包，新代码不要再使用。

### 第 7 章 ch07_memory —— 记忆与上下文管理
| 脚本 | 知识点 |
| --- | --- |
| `demo_trim_messages.py` | `trim_messages` 按 token 裁剪历史（离线演示） |
| `demo_agent_memory.py` | `create_agent` + `MemorySaver` checkpointer + `thread_id` 实现多轮记忆；不同 thread 之间记忆隔离 |

### 第 8 章 ch08_rag —— 检索增强生成
| 脚本 | 知识点 |
| --- | --- |
| `demo_documents.py` | `Document`（文本 + 元数据）；`RecursiveCharacterTextSplitter` 递归切分与重叠 |
| `demo_vectorstore.py` | `InMemoryVectorStore`；`as_retriever` 把向量库变成标准 Retriever（离线演示） |
| `demo_rag.py` | 两种 RAG 实现对比：LCEL 检索链（固定流程）vs RAG Agent（检索工具化，模型自主决策） |

> 说明：DeepSeek 暂无 Embeddings 接口，本章用自实现的 `HashingEmbeddings` 离线演示，
> 接口与真实嵌入完全一致，生产替换只需修改 `common/embeddings.py`。

### 第 9 章 ch09_streaming —— 流式与事件
| 脚本 | 知识点 |
| --- | --- |
| `demo_agent_stream.py` | Agent 三种流式模式：`values`（状态快照）/ `updates`（增量）/ `messages`（逐 token） |
| `demo_astream_events.py` | `astream_events(version="v2")` 细粒度事件流：`on_chain_start`、`on_chat_model_stream` 等 |

### 第 10 章 ch10_langgraph —— 状态图与人机协同
| 脚本 | 知识点 |
| --- | --- |
| `demo_stategraph.py` | `StateGraph` 三要素：State / Node / Edge；`add_conditional_edges` 条件路由（离线演示） |
| `demo_interrupt.py` | `interrupt()` 暂停图执行 + `Command(resume=...)` 恢复；checkpointer 持久化；高风险操作人工审批模式（离线演示） |

### 第 11 章 ch11_practice —— 综合实战：智能客服
| 脚本 | 知识点 |
| --- | --- |
| `knowledge_base.py` | 售后政策知识库构建（切分 + 向量库 + 检索器，第 8 章的落地） |
| `tools.py` | 业务工具三件套：`query_order` 查订单、`search_after_sale_policy` 政策检索（RAG 工具化）、`apply_refund` 退款登记 |
| `customer_service.py` | 完整组装：`create_agent` + 系统提示规范 + `MemorySaver` 多轮记忆 + 审计中间件 + `stream_mode="messages"` 打字机输出；三轮对话演示"查订单 -> 问政策 -> 申请退款"全链路 |
| `hitl_refund.py` | 人机协同（HITL）：自定义中间件 `wrap_tool_call` 拦截退款工具，金额超阈值时 `interrupt()` 暂停 Agent 等人工审批，`Command(resume=approve/reject)` 恢复执行；含小额免审、大额批准、大额拒绝三个场景 |

## 五、LangGraph 深入模块（langgraph_learn，lg01~lg10）

> 承接第 10 章入门，深入 LangGraph v1 的高级特性。
> 标注"离线"的脚本不消耗 API；标注"真实 API"的脚本调用 DeepSeek。

### lg01 图基础深入
| 脚本 | 知识点 |
| --- | --- |
| `demo_graph_anatomy.py`（离线） | 图拓扑自查：`get_graph().draw_mermaid()` 导出结构图；`.nodes` 查看；`get_state` 只读 checkpoint 不执行 |

### lg02 状态管理深入
| 脚本 | 知识点 |
| --- | --- |
| `demo_reducers.py`（离线） | 默认 LastValue 覆盖；`Annotated[list, add]` 累加（messages 机制基础）；自定义 reducer（打分取最高） |
| `demo_input_output_schema.py`（离线） | `input_schema`/`output_schema` 分离——内部字段不暴露给调用方；`config["configurable"]` 注入运行时上下文（不进状态不占 token） |

### lg03 并行计算
| 脚本 | 知识点 |
| --- | --- |
| `demo_parallel_nodes.py`（离线） | fan-out 扇出 / fan-in 汇聚 / barrier 屏障语义；并行分支写同名字段必须有 reducer |
| `demo_send_map_reduce.py`（离线） | `Send` 动态并行：条件边路由函数返回 `Send` 列表，运行时决定并行实例数（map-reduce 三段式） |

### lg04 子图
| 脚本 | 知识点 |
| --- | --- |
| `demo_subgraph.py`（离线） | 编译好的图直接当节点复用；不同 State 时的包装映射函数；子图可独立运行/测试 |

### lg05 多 Agent 系统（重点）
| 脚本 | 知识点 |
| --- | --- |
| `demo_supervisor.py`（真实 API） | 监督者模式：supervisor 结构化输出路由 + worker 各为 `create_agent` 子图 + `path_map` 映射 FINISH->END |
| `demo_handoff.py`（真实 API） | 交接模式（去中心化/Swarm 雏形）：worker 返回 `Command(goto=)` 直接转接并"带话" |

### lg06 人机协同深入
| 脚本 | 知识点 |
| --- | --- |
| `demo_command_navigation.py`（离线） | `Command(goto=)` 节点内动态导航替代条件边；`Command(update=)` 先改状态再跳转 |
| `demo_editor_review.py`（离线） | 双重 `interrupt`：审核→驳回→人工改稿→发布；`Command(resume=)` 逐层恢复 |

### lg07 持久化与时间旅行
| 脚本 | 知识点 |
| --- | --- |
| `demo_sqlite_checkpoint.py`（离线） | `SqliteSaver` 文件持久化；"模拟重启"验证跨进程记忆；thread 隔离（生产换 Postgres 后端 API 不变） |
| `demo_time_travel.py`（离线） | `get_state_history` 历史快照；`invoke(None, 历史config)` 纯回放；改输入分叉新时间线 |

### lg08 流式深入
| 脚本 | 知识点 |
| --- | --- |
| `demo_custom_writer.py`（离线） | `get_stream_writer()` 节点内发自定义事件（进度条场景）；`stream_mode=["custom","updates"]` 组合订阅 |
| `demo_subgraph_stream.py`（离线） | `subgraphs=True` 看子图内部流；namespace 元组标识来源——多 Agent 调试神器 |

### lg09 函数式 API
| 脚本 | 知识点 |
| --- | --- |
| `demo_entrypoint_task.py`（真实 API） | `@entrypoint`+`@task`：函数即图；多 task fan-out 并行；`invoke(None, config)` 从 checkpoint 恢复——已完成 task 不重跑（Durable Execution） |

### lg10 常见架构模式
| 脚本 | 知识点 |
| --- | --- |
| `demo_orchestrator_worker.py`（真实 API） | 编排者-工人：LLM 自拆任务清单 + `Send` 并行分发 + 汇总归并 |
| `demo_evaluator_optimizer.py`（真实 API） | 评估者-优化者：生成→评审打分→带反馈修订循环；轮数上限防死循环（self-refine 骨架） |

## 六、LangSmith 可观测模块（langsmith_learn，ls01~ls06）

> LangSmith 是 LangChain 官方的可观测/评估平台。所有演示**需要** `LANGSMITH_API_KEY`
>（[smith.langchain.com](https://smith.langchain.com) 免费注册，填入 `.env`）；
> 未配置时自动打印提示并跳过（退出码 0，不影响批量运行）。

### ls01 追踪基础
| 脚本 | 知识点 |
| --- | --- |
| `demo_tracing_context.py` | 开启追踪的两类方式：环境变量全局常开 vs `tracing_context` 上下文精确控制；`project_name`/`tags`/`metadata` 的隔离与检索价值 |

### ls02 @traceable 装饰器
| 脚本 | 知识点 |
| --- | --- |
| `demo_traceable_decorator.py` | 任意函数变可观测节点；嵌套 trace 树；`get_current_run_tree()` 拿 run_id；`process_inputs` 敏感参数脱敏 |

### ls03 Client 查询
| 脚本 | 知识点 |
| --- | --- |
| `demo_client_runs.py` | `list_runs` 查询记录；filter 语法（`eq(metadata.k,v)`/`has(tags,x)`/`gte(latency,2)`）；按 `trace_id` 还原完整调用树——线上排障与成本报表 |

### ls04 数据集与评估（重点）
| 脚本 | 知识点 |
| --- | --- |
| `demo_datasets.py` | `create_dataset`/`create_examples` 管理测试集；幂等处理；线上 trace 一键转用例 |
| `demo_evaluate.py` | `evaluate()` 跑分生成实验；规则型评估器 vs LLM-as-judge；改 prompt 后重跑对比回归 |

### ls05 Prompt Hub
| 脚本 | 知识点 |
| --- | --- |
| `demo_prompt_hub.py` | `push_prompt` 推版本 / `pull_prompt` 拉取使用 / `别名@版本` 锁定——Prompt 像依赖包一样管理 |

### ls06 LangGraph × LangSmith
| 脚本 | 知识点 |
| --- | --- |
| `demo_observe_langgraph.py` | 图运行自动逐层成 trace（定位卡点/token 消耗）；metadata 业务检索；`create_feedback` 人工反馈→数据集的飞轮闭环 |

## 七、deep-agents 深度代理模块（deepagents_learn，da01~da06）

> deepagents 是 LangChain 官方的"深度代理"框架——把 Claude Code / Deep Research 式
> 长时程 Agent 的产品化封装，基于第 6 章的 create_agent + 中间件体系组装。
> 版本说明：本工程使用 deepagents 0.7+，旧教程的 `builtin_tools=["planning"]`、
> 内置 PlanningTool 等 API 已被移除——规划改由 system_prompt/skills 体系承担。

### da01 快速上手
| 脚本 | 知识点 |
| --- | --- |
| `demo_deep_agent_basics.py`（真实 API） | `create_deep_agent` 一行创建；默认中间件栈（Filesystem/SubAgent/Summarization）；state 多出的 `files` 键；与普通 Agent 的设计差异（长时程/中间产物落文件/自动压缩） |

### da02 虚拟文件系统（上下文工程，重点）
| 脚本 | 知识点 |
| --- | --- |
| `demo_virtual_fs.py`（真实 API） | 8 个文件工具（write/read/edit/ls/glob/grep/delete/execute）；上下文工程：中间产物写文件不挤占对话、需要时再读回 |
| `demo_backends.py`（离线） | 存储后端可插拔：StateBackend（默认，随图状态/checkpoint）vs FilesystemBackend（真磁盘）vs StoreBackend（跨会话）/CompositeBackend（读写分离）；切换只改 `backend=` 一个参数 |

### da03 子代理委派
| 脚本 | 知识点 |
| --- | --- |
| `demo_task_tool.py`（真实 API） | 声明式 SubAgent（name/description/system_prompt/tools/model）；`task(subagent_type=..., description=...)` 派活；子代理独立上下文只回摘要；mode isolated/fork；与 lg05 多 Agent 组网的区别 |

### da04 定制扩展
| 脚本 | 知识点 |
| --- | --- |
| `demo_custom_middleware.py`（真实 API） | middleware 参数追加自定义 AgentMiddleware（wrap_tool_call 审计）；业务工具与文件工具共存 |
| `demo_state_memory.py`（离线） | DeepAgentState（messages+files）；memory 参数读 AGENTS.md 注入系统提示（sources 是文件路径且经 backend 读取，不污染对话历史）；skills 按需加载技能 |

### da05 人机协同
| 脚本 | 知识点 |
| --- | --- |
| `demo_interrupt_on.py`（真实 API） | `interrupt_on={"write_file": True}` 高危工具审批；`__interrupt__` 携带 action_requests/review_configs；`Command(resume={"decisions": [{"type": "approve"/"reject"/"edit"/"respond"}]})` 四种决策；permissions 的路径级 allow/deny/interrupt |

### da06 综合实战：深度研究助理
| 脚本 | 知识点 |
| --- | --- |
| `demo_research_assistant.py`（真实 API） | 完整 Deep Research 缩影：规划（plan.md）→ 3 次 researcher 子代理调研（笔记落盘）→ critic 审查修订 → 汇总 report.md；recursion_limit 放宽；换 tools 即变领域专家 |

## 八、学习流程建议

> 📚 **复习笔记**：
> ① LangChain 基础见
> [docs/LangChain v1 _ LangGraph v1 核心知识点完整总结.md](docs/LangChain%20v1%20_%20LangGraph%20v1%20%E6%A0%B8%E5%BF%83%E7%9F%A5%E8%AF%86%E7%82%B9%E5%AE%8C%E6%95%B4%E6%80%BB%E7%BB%93.md)
> ② LangGraph / LangSmith / deep-agents 三大模块见
> [docs/LangGraph _ LangSmith _ deep-agents 核心知识点完整总结.md](docs/LangGraph%20_%20LangSmith%20_%20deep-agents%20%E6%A0%B8%E5%BF%83%E7%9F%A5%E8%AF%86%E7%82%B9%E5%AE%8C%E6%95%B4%E6%80%BB%E7%BB%93.md)
> （均含知识地图、易混淆点对比表、踩坑实录、API 背诵卡与自测清单）。

1. **环境搭建**：创建 venv、装依赖、配 `.env`，跑通 `pytest tests/ -v`（全部离线）。
2. **打底（第 1~4 章）**：理解 Runnable 统一接口、消息体系、Prompt 模板、LCEL 管道——这是 LangChain 的"语法"。
3. **核心（第 5~6 章）**：先手写一遍 Tool Calling 闭环，再学 `create_agent`，体会框架帮你封装了什么；中间件是 v1 最重要的新机制。
4. **进阶（第 7~9 章）**：记忆、RAG、流式——构建生产级应用的三块拼图。
5. **深入（第 10 章）**：LangGraph 状态图——`create_agent` 的底层运行时，复杂工作流与人机协同的最终形态。
6. **LangGraph 进阶（lg01~lg10）**：学完第 10 章后进入本模块——reducer/并行 Send/子图是构建复杂系统的地基；
   多 Agent（lg05）与架构模式（lg10）是当前业界主流用法；持久化/时间旅行（lg07）是生产级长流程的关键。
7. **实战（第 11 章）**：智能客服综合案例——试着给它加新工具、换知识库、接真实嵌入，改造成你自己的业务 Agent。
8. **可观测（ls01~ls06）**：注册 LangSmith 拿到 Key 后学习——追踪（ls01-03）先跑通，
   再学评估（ls04）与 Prompt 管理（ls05），最后看图应用观测（ls06）。
   没有 Key 也可先读代码理解 API 用法。
9. **深度代理（da01~da06）**：学完第 6 章（create_agent/中间件）与 lg 系列后进入——
   da02 的上下文工程与 da03 的子代理是 deep agents 的灵魂；da06 把全部知识组装成
   深度研究助理，试着换 tools/换主题改造成自己的领域 Agent。

## 九、常见问题

- **报错 `未检测到 DEEPSEEK_API_KEY`**：根目录缺少 `.env`，参照 `.env.example` 创建。
- **PyCharm 报找不到解释器**：打开项目后 PyCharm 会自动检测 `.venv`；若未识别，手动选择
  `设置 -> 项目 -> Python 解释器 -> 添加现有解释器 -> <项目根目录>\.venv\Scripts\python.exe`。
- **想换模型**：修改 `.env` 中的 `DEEPSEEK_MODEL`（如 `deepseek-chat`、`deepseek-reasoner`），代码零改动。
- **旧代码里的 `LLMChain` / `create_react_agent` 跑不通**：属于 v0.x API，请改用 LCEL 管道与
  `langchain.agents.create_agent`，或安装 `langchain-classic` 过渡。
- **结构化输出报 `Thinking mode does not support this tool_choice`**：DeepSeek 思考型模型
  （deepseek-flash）的思考模式与强制 tool_choice 冲突。用 `common/llm.py` 的
  `get_structured_model(schema)`（内部已关 thinking + 走 function_calling）。
- **节点返回 Send 列表报 `InvalidUpdateError`**：`Send` 只能由 `add_conditional_edges` 的
  路由函数返回，节点本身返回 dict（参见 lg03/lg10）。
- **LangSmith 示例打印"[跳过]"**：正常行为。到 smith.langchain.com 注册免费账号，
  在 `.env` 填 `LANGSMITH_API_KEY=lsv2_pt_xxxx` 后重跑即可真实上报。
- **ls05 提示"Workspace 还没有设置 handle"**：Prompt Hub 的别名格式是 `owner/prompt名`，
  个人 Workspace 默认无 handle。到 Smith 网页 Settings -> Workspace 设置一个全局唯一的
  Handle 后重跑，或在 `.env` 中配 `LANGSMITH_PROMPT_OWNER=你的handle`。
- **`python run_all.py lg05` 报未知章节**：请先 `pip install -r requirements.txt`
  更新依赖（新增 langgraph-checkpoint-sqlite）。
- **deepagents 报 `cannot import name 'AgentMiddleware' from 'langchain.agents'`**：
  AgentMiddleware 在 `langchain.agents.middleware` 子模块（deepagents 0.7 起与顶层导出解耦）。
- **deep-agents 的 memory 注入了 "(No memory loaded)"**：memory 的 sources 是
  **文件路径**且经 backend 读取——默认 StateBackend 是空的，需配
  `backend=FilesystemBackend(root_dir=目录)` 且 memory=["AGENTS.md"]（见 da04）。
- **FilesystemBackend 下文件没写进 root_dir**：以 `/` 开头的绝对路径会逃出
  root_dir（Windows 上直指盘符根），相对路径才受约束；生产务必搭配 permissions
  做路径级管控（见 da02/da05）。
- **旧教程的 `create_deep_agent(builtin_tools=["planning"])` 报错**：0.7 已移除内置
  planning 工具，规划交给 system_prompt 约定 + skills 体系。