Markdown-first knowledge notes
Knowledge Notes
面向多个技术主题的知识笔记展示站，用统一模板组织学习文档、源码阅读和实践路线。
在首页展开文档
第 1 章：真实模型与消息
init_chat_model、消息对象与一次真实 ainvoke 调用。
第 2 章：状态与动态路由
MessagesState、reducer、StateGraph 与 Command 路由。
第 3 章：结构化输出
Pydantic schema 与 with_structured_output 的可控决策。
第 4 章：工具循环
工具绑定、ToolMessage 与真实 ReAct 闭环。
第 5 章：搜索与 MCP
搜索工具、MCP 装配与外部工具边界。
第 6 章：子图与并发
supervisor/researcher 子图、asyncio.gather 与汇总。
第 7 章：持久化、流式与观测
checkpointer、thread_id、LangSmith 与事件流。
第 8 章：综合迷你研究员
把前七章知识点串成离线 mini researcher。
第 9 章：项目知识覆盖矩阵
将概念、项目源码和真实示例映射为学习矩阵。
第 10 章：从用户问题到最终报告的完整链路
追踪澄清、简报、并发研究和报告生成的数据流。
第 11 章：配置、密钥、身份与运行时边界
RunnableConfig、密钥来源、MCP 和 owner 授权边界。
第 12 章：容错、测试、评估与升级判断
重试、上下文限制、并发异常和 API 升级策略。
第 13 章：源码阅读练习
围绕 reducer、工具协议、配置和异常路径的练习。
第 14 章：旧版与当前版 API 对照
学习目标
第 15 章：主 Agent、子 Agent 与结构化数据交接
学习目标
在首页展开文档
第 1 章：构造 `create_agent`
目标
第 1 章：Prompt 与消息模板
学习目标
第 2 章：LCEL 与 Runnable
学习目标
第 2 章：消息、Prompt、工具与结构化输出
消息协议
第 3 章：标准 Agent 与 Middleware
学习目标
第 3 章：短期记忆
短期记忆是同一对话 thread 的 Agent state 持久化，不是模型自己的记忆。给 createagent 传 checkpointer=InMemorySaver()，每次调用传相同 config={"configurable": {"threadid": "..."}}，第二轮就会恢复第一轮写入的 mes
第 4 章：文档、切分、Embedding 与 Retriever
学习目标
第 4 章：长期记忆与 Store
长期记忆是跨 thread 的受控数据。Store 挂在编译 Agent 上，工具通过 ToolRuntime.store 读取；namespace 必须包含已认证用户 id，避免 A 用户读到 B 用户的偏好。
第 5 章：RAG 检索 Agent
学习目标
第 5 章：流式输出与观测
ainvoke 适合只要最终 state；astream 适合 UI 或实时日志；astreamevents(version="v2") 适合查看 Runnable/Agent 的嵌套生命周期。三者都执行真实工作，不要为了“流式”重复调用 Agent。
第 6 章：预制 Middleware
Middleware 在模型或工具节点前后执行，解决横切问题，不承担业务状态机。按顺序传入 middleware=[...]；顺序会影响谁先观察和修改请求。
第 6 章：Runnable 观测与生产边界
学习目标
第 7 章：自定义 `AgentMiddleware`
只在预制 middleware 无法表达需求时自定义。常用钩子：beforeagent/afteragent 观察整次运行，beforemodel/aftermodel 修改或检查 state，wrapmodelcall 动态选择模型，wraptoolcall 拦截单次工具。
第 8 章：人在回路（HITL）
对有外部副作用的工具使用 HumanInTheLoopMiddleware。它在模型提出匹配工具调用后生成 LangGraph interrupt；调用方展示 action，再以 Command(resume={"decisions": [...]}) 恢复。必须配 checkpointer，否则没有可恢复状态。
第 9 章：Context engineering
Context engineering 是把有限、可信、任务相关的信息在正确时机交给模型，不是把所有数据拼进 system prompt。一个可审查顺序是：稳定规则 最近消息 已验证工具结果 当前任务所需的最小长期记忆 模型调用。
第 10 章：子 Agent 与结构化交接
子 Agent 的目的不是把任何函数都拆成 Agent，而是隔离专业工具、上下文和失败边界。父 Agent 只传任务契约，子 Agent 只返结果契约，禁止把完整父对话、认证信息或所有 Store 内容直接转发。
第 11 章：综合 Agent
[16integratedagent.py](examples/16integratedagent.py) 组合标准 Agent 的必要部件：
在首页展开文档
主题Skills
主题Memory / 记忆
主题Context Engineering
主题Backends / 后端
主题Subagents / 子 Agent
主题Human-in-the-loop / 人机回路
主题Frontend / 前端
Deep Agents Frontend 学习路线
学习主题
01 概述：真实链路与 useStream 暴露了什么
它是什么
02 Subagent streaming：把专家子代理单独展示
它是什么
03 Todo list
它是什么
04 Sandbox
它是什么
05 Frontend HITL
它是什么
06 Dynamic Tools
它是什么
07 MCP + Skills 严格选择
它是什么
08 LangGraph Graph Execution
它是什么
09 Custom Stream Channels
它是什么
10 Markdown Messages
它是什么
11 Tool Calling
它是什么
12 Headless Tools
它是什么
13 Human-in-the-loop
它是什么
14 Branching Chat
它是什么
15 Reasoning Tokens
它是什么
16 Structured Output
它是什么
17 Message Queues
它是什么
18 Join & Rejoin Streams
它是什么
19 Time Travel
它是什么
20 Generative UI
它是什么
21 Frontend Integrations Overview
本章目标
22 Frontend Integration Examples
本章目标
主题Profiles / 模型配置
主题Advanced / 高级能力
Deep Agents 高级能力教学
这个目录继续学习 Deep Agents 里更靠近生产的能力。每章只做一个核心概念，代码放在 deepagentsrc/advancedteach/，讲义放在 deepagentsrc/advancedteach/docs/。
01 Interpreter 与 PTC
Interpreter 是 Deep Agents 的一个轻量代码执行层：模型不只发普通工具调用，还可以写一段 JavaScript 让运行时执行。PTC 是 Programmatic Tool Calling，它把允许的工具暴露到 Interpreter 的 tools 命名空间里，让代码循环、分支、并行调用工具。它
02 Sandbox 生命周期
Sandbox 是 Deep Agents 的执行环境后端：它让 Agent 不只读写文件，还能通过 execute 跑命令。生命周期问题解决的是“这个环境什么时候创建、什么时候复用、什么时候销毁”。生产里最常见的是 threadscoped：每个 conversation 一个 sandbox，同一个 threadi
第三章：Event Streaming
Event Streaming 是把一次 Agent 运行拆成连续事件：模型消息、工具开始/结束、状态快照和最终输出都会按运行过程吐出来。它解决的是前端不能只等最终答案的问题，IDE、聊天窗口、工具执行面板都需要边跑边更新。Deep Agents 继承 LangGraph 的流式协议，并额外提供面向子代理的 subag
第四章：Fault Tolerance
Fault Tolerance 是让 Agent 在真实生产错误里继续可靠工作的能力。它不是把所有异常吞掉，而是按错误类型分流：临时网络错误自动重试，可由模型修正的工具错误转成 ToolMessage，需要人判断的操作交给 HITL，无法处理的未知异常直接暴露给开发者。
第五章：Going to Production
生产 Deep Agent 的核心不是“把本地 agent 变量直接部署出去”，而是让每个 run 带着稳定的 threadid 和本次请求的 context。当后端资源依赖 threadid，例如 threadscoped sandbox 时，导出的 Agent 应该是 async graph factory：平台每
第六章：Rubric 与 Evaluation
Rubric 是把“做好”写成可判断标准，避免只凭感觉说 Agent 输出不错。RubricMiddleware 在一次 Deep Agent 运行内做 runtime LLMasajudge：工作 Agent 输出后，独立 grader 依据 rubric 给出 satisfied、needsrevision 或 f
第七章：Multimodal
Deep Agents 的内置 readfile 不只读文本。对受支持的图片、PDF、音视频文件，它会返回标准多模态 content blocks，让支持对应模态的模型直接检查文件内容，而不是把二进制转成乱码塞进 prompt。
第八章：模型能力注册表与运行时模型路由
模型名称不是能力声明。前端可以提交 modelid，但服务端必须用受控注册表确认它确实允许使用，并且满足本轮任务的能力要求；不能把任意 provider/model 字符串直接透传给 initchatmodel。
主题Middleware / 中间件
Middleware 学习路线
这组小章节专门补 Deep Agents / LangChain / LangGraph 里的 middleware。代码放在 deepagentsrc/middlewareteach/，讲义放在 deepagentsrc/middlewareteach/docs/。
第一章：生命周期钩子 `before_model` / `after_model`
这两个 hook 是最基础的 middleware 入口：beforemodel 在每次模型调用前执行，aftermodel 在模型返回后执行。它们适合做日志、限流标记、状态统计、轻量校验；不适合改写整个模型调用流程，那是 wrapmodelcall 的活。
第二章：`wrap_model_call`
wrapmodelcall 是包住模型调用的 middleware：你可以选择调用 handler(request)，也可以不调用它直接返回。它解决的是模型层控制问题，比如改模型请求、统计调用、fallback、缓存命中、短路返回。
第三章：`wrap_tool_call`
wraptoolcall 是包住工具执行的 middleware：它拿到模型发出的 tool call，调用 handler(request) 后工具才会真正执行。它解决的是工具层控制问题，例如审计、重试、错误转译、结果改写和敏感信息过滤。
第四章：Deep Agents 默认 middleware 栈
Deep Agents 不是另起炉灶的 Agent runtime，它是把 LangChain agent loop 和一组默认 middleware 打包成 harness。createdeepagent(..., middleware=[...]) 里的自定义 middleware 会插入 Deep Agents
第五章：综合案例
本章把 wrapmodelcall、wraptoolcall 和 createdeepagent 放到同一条真实流程里。wrapmodelcall 观察模型层调用，并对临时上游错误做最小重试；wraptoolcall 观察并改写工具结果；Deep Agent 负责真实调用模型并决定工具调用。
06 类中间件与 `state_schema`
AgentMiddleware 类写法适合把多个 hook 和它们共享的配置放在一起。stateschema 用来扩展 agent state，让 middleware 能把计数、标记、审计结果这类运行时信息写回最终 state。它不是全局变量，也不是系统提示词，作用域是这次 agent run 的状态。
主题A2A / 远程 Agent
A2A 教学
这个目录学习如何把 Deep Agent 暴露成标准 A2A Server，以及如何作为 Client 调用远端 Agent。
第一章：通过 A2A 暴露 Deep Agent
A2A 是 AgenttoAgent 协议：调用方先读取远端的 Agent Card，了解它的接口和 Skill 元数据，再发送任务并接收 Message 或 Task。它不是 Deep Agent 的 task 工具，也不是 MCP；本例把一个真实 Deep Agent 包在 A2A Server 中，让另一个 A2
第二章：A2A 流式状态、超时和取消
代码在 deepagentsrc/a2ateach/02streamingandcancel.py。
第三章：认证与远端能力授权
代码在 deepagentsrc/a2ateach/03authandremotecapabilities.py。
第四章：多个远端 A2A Agent 编排
代码在 deepagentsrc/a2ateach/04multiagentorchestration.py。