工作原理与设计权衡

·整体架构：一层协议 + 一道下沉边界

把这一章所有机制放进一张图，LangChain v1.0 的形状就清楚了：底层是 Runnable 协议，| 在协议上把组件组合成 LCEL 链；当线性链表达不了的需求出现，整条管道就"下沉"到 LangGraph 执行引擎——而 create_agent 正是已经站在那条边界另一侧的高层入口。

2.1Runnable 设计机制：能力为什么长在接口上

统一接口先逼出组合性，组合性再让 stream / batch / retry / fallback 只需在协议层实现一次。

01 章把 Runnable 当词汇引入（见 §1.1）：一个统一接口，凡实现它的对象都有 invoke / stream / batch。这一节回答更深的问题——为什么把接口统一，就能让一连串高级能力"自动"出现。

运行方式拆成两步因果链。第一步，统一接口逼出组合性：因为 prompt、model、parser 都暴露同一种"吃一个输入、吐一个输出"的形状，RunnableSequence（也就是 a | b | c 编译出的对象）才能把它们首尾相接，而不必关心每一段内部是什么。第二步，组合性让能力下沉到协议层：RunnableSequence 实现 batch 的方式，是对它持有的每一个子 Runnable 依次调用各自的 batch；它实现 stream 的方式，是把上一段的流式输出接到下一段的流式输入。于是只要协议层把"组合体如何 batch、如何 stream、如何 retry、如何 fallback"定义清楚一次，任意一条新链——哪怕组件是你今天刚写的——立刻就拥有这四项能力。能力是接口的性质，不是组件逐个攒出来的功能。

# 演示：能力来自组合结果，不来自任一组件（2026-06，未本机执行）
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain.chat_models import init_chat_model

prompt = ChatPromptTemplate.from_template("一句话解释 {topic}")
model  = init_chat_model("openai:gpt-5.4")
parser = StrOutputParser()

chain = prompt | model | parser          # 编译出一个 RunnableSequence

# .batch 不是 prompt 的、也不是 model 的方法；
# 它是 chain（组合结果）的方法 —— 协议层统一实现的。
results = chain.batch([
    {"topic": "向量检索"},
    {"topic": "重排序"},
    {"topic": "提示注入"},
])
# 三条输入并发跑完，返回三个字符串。没有任何组件单独写过 batch 逻辑。

chain 是 RunnableSequence；| 编译的产物。 .batch 定义在协议层，对每个子 Runnable 各调一次它自己的 batch —— 这就是"组合性让能力下沉"的字面含义。

2.2LCEL 何时够、何时下沉 LangGraph

LCEL 只表达线性无状态 DAG；出现分支 / 循环 / 检查点 / 人工中断 / 中途可观测，就到了边界，要换 LangGraph。

运行方式：| 编译出的 RunnableSequence 本质是一张有向无环图——数据从入口单向流到出口，每个节点执行一次，没有回头边。RunnableParallel 能让它分叉再汇合，但仍然无环、仍然每节点一次。这意味着 LCEL 能优雅表达的，恰好是"输入 → 一串确定的变换 → 输出"这类线性、无状态的流程：prompt 拼装、模型调用、解析、RAG 的检索-拼接-生成，都落在这里。

边界从哪里开始？当流程需要"根据中间结果决定下一步走哪条路"（条件分支）、"反复执行直到满足某条件"（循环，agent 的工具调用循环就是典型）、"把执行暂停、存盘、之后恢复"（检查点 / 持久化）、"中途交给人确认再继续"（human-in-the-loop，下称 HITL）、或"逐节点观测与回放状态"——这五类需求里任意一条出现，DAG 模型就表达不了了。因为它们都要求"带状态地、允许成环地"推进，而这正是 StateGraph 的定义域：显式的状态对象、节点、可以成环的边、内建检查点。

2.3Agent API 三次迁移：从黑盒到可控状态图

三代入口同一条主线——把 agent 的"思考-调用工具-再思考"循环，从藏在黑盒里逐步搬到可观测、可干预的状态图上。

运行方式：agent 的内核都是同一个循环——模型决定调哪个工具、执行工具、把结果喂回模型、再决定下一步，直到模型认为任务完成。三代 API 的差异不在这个循环本身，而在这个循环对你是否透明、能否在中途干预。第一代 AgentExecutor 把循环封在内部，你只能从外面传工具、收结果，循环中途的状态拿不到、改不了。第二代 create_react_agent（来自 langgraph.prebuilt）把循环重写成一张 LangGraph 图，循环第一次变成可观测、可加检查点的对象。第三代 create_agent（来自 langchain.agents）在第二代的图之上加了 middleware（中间件）层，让你能在循环的具体节点前后插入自定义逻辑，而不必亲手改图。

# 三代 agent 入口对照（2026-06，未本机执行）

# 第一代 —— AgentExecutor（黑盒循环，维护到 2026-12）
# from langchain.agents import AgentExecutor, create_tool_calling_agent
# agent = create_tool_calling_agent(model, tools, prompt)
# executor = AgentExecutor(agent=agent, tools=tools)   # 循环封在内部，中途状态不可见

# 第二代 —— create_react_agent（已弃用，原在 langgraph.prebuilt）
# from langgraph.prebuilt import create_react_agent
# agent = create_react_agent(model, tools)             # 循环已是 LangGraph 图，但入口被 v1.0 迁走

# 第三代 —— create_agent（当前推荐入口）
from langchain.agents import create_agent

agent = create_agent("openai:gpt-5.4", tools=tools)    # 跑在 LangGraph runtime 上；
                                                       # 可挂 middleware 在循环节点前后插逻辑
result = agent.invoke({"messages": [{"role": "user", "content": "查一下今天的汇率"}]})

create_agent 来自 langchain.agents，模型可直接用 "provider:model" 字符串。 middleware 是第三代相对第二代的关键增量——把"改循环行为"从"改图"降级成"挂钩子"。

2.4LangChain 跑在 LangGraph 上（v1.0）：互补，不是二选一

2025-10 起 create_agent 跑在 LangGraph 执行引擎上；它是高层入口，要更多控制就下沉到 StateGraph——同一连续谱的两端。

运行方式：v1.0 之前，很多人把 LangChain 和 LangGraph 当成两个要"选一个"的框架。v1.0（2025-10-22）之后，这个对立被取消了——LangChain 的 agent 直接构建在 LangGraph runtime 之上。官方的定位是：LangChain 是"构建 agent 最快的方式"，LangGraph 是"更底层的框架与运行时，用于高度定制、高度可控的 agent"。create_agent 用一句 "Agent = Model + Harness" 概括：harness（模型外围的那套循环、工具、middleware）由 LangGraph 引擎提供，你拿到的是预组装好的高层入口。

关键的心智模型是连续谱而非两个孤岛：同一个 agent 需求，可以停在 create_agent（高层、少代码、middleware 调参），也可以一路下沉到手写 StateGraph（底层、全控制、自定义拓扑），中间没有需要换框架的断点——因为它们本就是同一套引擎的不同高度。create_agent 的产物仍是一个可 invoke / stream 的 Runnable（呼应图 2.0 最底层），所以下沉前后，对外的调用形状不变。

2.5备选方案与痛点：综合一张表

把前四节的设计选择并排：每个"没有它时手写什么"的痛点，对应 LangChain 的一个机制，也各自留下一笔代价。

前四节分别拆了一个机制。这一节把它们拼回一张总表，用"痛点 → 设计回应 → 代价"的三栏，让整套设计的取舍一眼可比——这也是评审或选型时最该带在手边的一张表。

·跨概念综合：一个场景里串起三件事

把 Runnable、LCEL 边界、下沉判断揉进一个具体场景，看它们如何协同。