# LangChain 生态架构解析：从 LangGraph 编排到 LangSmith 生产部署

> LangChain生态通过分层架构解耦智能体开发、编排与部署。LangGraph作为底层运行时，提供状态管理、持久化执行及人机协同能力；LangChain框架层封装模型、工具及中间件，简化开发；

原文：/knowledge/crawler-4b466e8281a59a691b4b027de49812b40535e5e472ea5df8c4636811ed15a170

LangChain 生态提供了一套分层架构，将智能体（Agent）的开发、编排与生产部署解耦。该架构主要由三个核心组件构成：作为底层编排运行时的 **LangGraph**、作为高层框架的 **LangChain** 以及作为生产级部署平台的 **LangSmith Agent Server**。这种分层设计使得开发者可以在保持底层控制力的同时，利用高层抽象加速开发，并无缝接入企业级运维能力。

*   **LangGraph**：低层级的编排框架与运行时，负责状态管理、持久化执行、流式处理及人机协同（Human-in-the-loop）。
*   **LangChain**：智能体框架层，提供模型、工具、中间件（Middleware）及智能体循环（Agent Loop）的抽象。
*   **LangSmith Agent Server**：生产级部署运行时，提供 API 接口、任务队列、持久化存储及多模型支持，用于托管和扩展智能体应用。

此外，**Deep Agents** 作为智能体 Harness（Harness），在 LangGraph 之上预装了文件系统、子智能体、摘要等中间件，用于处理长运行任务。

[来源1](https://docs.langchain.com/oss/python/langgraph/overview)

## 1. 核心组件职责划分

在 LangChain 生态中，各组件职责明确，形成从开发到部署的完整链路。

### 1.1 LangGraph：编排运行时 (Orchestration Runtime)

LangGraph 是一个低层级的编排框架和运行时，专为长运行、有状态（Stateful）的智能体设计。它不强制规定提示词或特定的智能体架构，而是提供构建工作流的图原语。

*   **核心能力**：
    *   **持久化执行 (Durable Execution)**：通过检查点（Checkpoints）保存状态，支持故障恢复和暂停/继续执行。
    *   **流式处理 (Streaming)**：支持流式输出 Token、状态更新及事件。
    *   **人机协同 (Human-in-the-loop)**：允许在执行过程中暂停，由人类审查或编辑状态后继续。
    *   **混合步骤**：在同一个图中混合确定性代码步骤与 LLM 驱动的代理步骤。

LangGraph 是 LangChain 生态中处理复杂控制流和状态管理的基石。

[来源1](https://docs.langchain.com/oss/python/langgraph/overview)

### 1.2 LangChain：高层框架 (Agent Framework)

LangChain 提供智能体框架层，封装了模型集成、工具调用、中间件及智能体循环。它基于 LangGraph 构建，为开发者提供高级抽象。

*   **核心能力**：
    *   **智能体创建 (`create_agent`)**：提供统一的接口创建智能体，支持多种模型后端（如 OpenAI, Anthropic, Google 等）。
    *   **中间件系统 (Middleware)**：通过中间件机制扩展智能体功能，包括上下文管理、容错、规划、护栏（Guardrails）等。
    *   **状态管理 (`AgentState`)**：定义智能体的执行上下文，包含消息历史及自定义字段。
    *   **结构化输出**：支持通过 Pydantic 模型定义智能体的响应格式。

LangChain 框架层简化了智能体的开发，开发者可以使用 `create_agent` 快速构建具备工具调用、记忆和流式输出能力的智能体，而无需直接操作 LangGraph 的图节点。

[来源1](https://docs.langchain.com/oss/python/langchain/agents)

### 1.3 Deep Agents：智能体 Harness

Deep Agents 是 LangChain 生态中的智能体 Harness，专为长运行的编码和研究任务设计。它在 LangGraph 之上预装了常用的中间件栈。

*   **预装中间件**：包括文件系统中间件（FilesystemMiddleware）、摘要中间件（SummarizationMiddleware）、记忆中间件（MemoryMiddleware）和技能中间件（SkillsMiddleware）。
*   **子智能体支持**：内置对子智能体（Subagents）的支持，允许主智能体将任务委派给专门的子智能体。

Deep Agents 通过 `create_deep_agent` 函数创建，开发者只需安装 `deepagents` 包即可使用。它降低了构建复杂、长运行智能体的门槛，同时保留了 LangGraph 的底层控制力。

[来源1](https://docs.langchain.com/oss/python/langchain/agents) · [来源2](https://docs.langchain.com/oss/python/langgraph/overview)

## 2. LangGraph 核心机制：状态与编排

LangGraph 的核心在于通过图结构管理智能体的状态和执行流程。

[来源1](https://docs.langchain.com/oss/python/langgraph/overview)

### 2.1 状态管理 (State Management)

LangGraph 使用共享状态图（Shared State Graph）来管理智能体的上下文。状态是一个类型化的字典（Typed Dictionary），包含消息历史和自定义字段。

*   **内置字段**：`messages` 列表，用于存储完整的对话历史，采用追加模式（Append-only）。
*   **自定义状态**：开发者可以子类化 `AgentState` 或 `MessagesState` 来添加自定义字段（如 `user_id`, `call_count`）。

```python
from langgraph.graph import StateGraph, MessagesState, START, END

def mock_llm(state: MessagesState):
    return {"messages": [{"role": "ai", "content": "hello world"}]}

graph = StateGraph(MessagesState)
graph.add_node(mock_llm)
graph.add_edge(START, "mock_llm")
graph.add_edge("mock_llm", END)
graph = graph.compile()

graph.invoke({"messages": [{"role": "user", "content": "hi!"}]})
```

状态管理支持持久化检查点（Checkpoints），允许智能体在故障后从检查点恢复执行。

[来源1](https://docs.langchain.com/oss/python/langchain/agents) · [来源2](https://docs.langchain.com/oss/python/langgraph/overview)

### 2.2 流式处理 (Streaming)

LangGraph 支持流式处理，允许在智能体执行过程中实时获取中间状态和工具调用信息。通过 `stream_events` 方法，开发者可以监听不同版本的事件流（如 `v3`）。

```python
stream = agent.stream_events(
    {"messages": [{"role": "user", "content": "Search for AI news"}]},
    version="v3",
)
for snapshot in stream.values:
    latest_message = snapshot["messages"][-1]
    if latest_message.tool_calls:
        print(f"Calling tools: {[tc['name'] for tc in latest_message.tool_calls]}")
```

流式处理对于长运行任务至关重要，它提供了实时的进度反馈。

[来源1](https://docs.langchain.com/oss/python/langchain/agents)

## 3. LangChain 框架层：中间件与上下文

LangChain 框架层通过中间件（Middleware）机制扩展智能体功能，解决了上下文管理、容错和规划等核心问题。

[来源1](https://docs.langchain.com/oss/python/langchain/agents)

### 3.1 上下文管理 (Context Management)

由于模型上下文窗口有限，LangChain 提供了多种中间件来管理上下文：

*   **摘要中间件 (SummarizationMiddleware)**：在上下文溢出前压缩历史记录。
*   **记忆中间件 (MemoryMiddleware)**：在启动时加载持久化指令，使智能体跨会话保持知识。
*   **技能中间件 (SkillsMiddleware)**：按需加载领域知识，避免一次性加载所有内容。

```python
from deepagents.backends import StateBackend
from deepagents.middleware import (
    FilesystemMiddleware, 
    MemoryMiddleware, 
    SkillsMiddleware, 
    SummarizationMiddleware
)

backend = StateBackend()
agent = create_agent(
    model="openai:gpt-6.1-sol",
    tools=[search],
    middleware=[
        FilesystemMiddleware(backend=backend),
        SummarizationMiddleware(model=model, backend=backend),
        MemoryMiddleware(backend=backend, sources=["./AGENTS.md"]),
        SkillsMiddleware(backend=backend, sources=["./skills/"]),
    ],
)
```

### 3.2 容错与重试 (Fault Tolerance)

生产环境中，API 限流、超时和瞬态错误是常态。LangChain 提供了模型重试中间件（ModelRetryMiddleware）和工具重试中间件（ToolRetryMiddleware），在基础设施层面处理这些错误，无需在业务逻辑中添加 try/catch。

```python
from langchain.agents.middleware import ModelRetryMiddleware, ToolRetryMiddleware

agent = create_agent(
    model="openai:gpt-6.1-sol",
    tools=[search],
    middleware=[
        ModelRetryMiddleware(max_retries=3),
        ToolRetryMiddleware(max_retries=2),
    ],
)
```

### 3.3 子智能体与规划 (Subagents & Planning)

LangChain 支持通过子智能体中间件（SubAgentMiddleware）将任务委派给专门的子智能体，实现并行和隔离的工作。同时，待办列表中间件（TodoListMiddleware）支持任务规划。

```python
from deepagents.middleware.subagents import SubAgentMiddleware

agent = create_agent(
    model="openai:gpt-6.1-sol",
    tools=[search],
    middleware=[
        TodoListMiddleware(),
        SubAgentMiddleware(
            backend=backend,
            subagents=[
                {
                    "name": "researcher",
                    "description": "Searches and returns a structured summary.",
                    "system_prompt": "Use the search tool...",
                    "tools": [search],
                    "model": "anthropic:claude-sonnet-4-6",
                }
            ],
        ),
    ],
)
```

### 3.4 结构化输出 (Structured Output)

LangChain 支持通过 Pydantic 模型定义智能体的响应格式，确保输出符合预期结构。

```python
from pydantic import BaseModel
from langchain.agents import create_agent

class Answer(BaseModel):
    summary: str
    confidence: float

agent = create_agent(
    model="openai:gpt-6.1-sol",
    tools=tools,
    response_format=Answer
)
result = agent.invoke({"messages": [{"role": "user", "content": "Summarize AI trends"}]})
print(result["structured_response"])  # Answer(summary=..., confidence=...)
```

### 3.5 上下文与线程 (Context & Thread)

在调用智能体时，`thread_id` 用于限定对话范围（消息历史、检查点），而 `context` 用于携带每次运行的数据（如 `user_id`）。两者通常结合使用。

```python
from langchain_core.utils.uuid import uuid7
from langgraph.checkpoint.memory import InMemorySaver

agent = create_agent(
    model="openai:gpt-6.1-sol",
    tools=[],
    context_schema=Context,
    checkpointer=InMemorySaver(),
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "What's the weather?"}]},
    config={"configurable": {"thread_id": str(uuid7())}},
    context=Context(user_id="user-123"),
)
```

[来源1](https://docs.langchain.com/oss/python/langchain/agents)

## 4. LangSmith Agent Server：生产级部署

LangSmith Agent Server（原 LangSmith Deployment）是 LangChain 生态中的生产级部署运行时。它将智能体应用转化为可管理的 API 服务，支持持久化、任务队列和多模型扩展。

### 4.1 核心概念

*   **助手 (Assistant)**：配置好的智能体蓝图，对应一个或多个图（Graph）。
*   **线程 (Thread)**：代表一次对话或任务上下文，包含消息历史和状态。
*   **运行 (Run)**：线程中的一次具体执行实例。
*   **定时任务 (Cron Jobs)**：支持后台调度的自动化任务。

### 4.2 部署架构

Agent Server 采用无状态容器架构，由 API 服务器和队列工作器（Queue Workers）组成，共享 PostgreSQL 和 Redis 存储。

*   **API 服务器**：处理客户端请求（创建运行、读取状态、流式输出），不执行智能体代码。
*   **队列工作器**：执行引擎，监听任务队列，执行图代码，写入检查点。
*   **持久化存储**：
    *   **PostgreSQL**：存储核心资源（助手、线程、运行）、检查点（短期记忆）和存储（长期记忆）。
    *   **Redis**：处理信号、取消和流式发布的 pub/sub 通信，仅存储临时数据。

```mermaid
flowchart TB
    User["User"]
    API["API Servers"]
    subgraph WorkerContainer["Worker Containers"]
        QueueLoop["Queue Loop"]
        W1["Worker"]
        W2["Worker"]
    end
    DB[(Postgres)]
    Redis[(Redis)]

    User -->|request| API
    API -->|create run| DB
    API -->|notify| Redis
    Redis -->|wake| QueueLoop
    QueueLoop -->|claim next run| DB
    WorkerContainer -->|save checkpoints| DB
    WorkerContainer -->|publish events| Redis
    Redis -->|stream events| API
    API -->|SSE response| User
```

### 4.3 部署模式

*   **单主机 (Single Host)**：API 服务器和队列工作器在同一主机上，适合开发和低流量场景。
*   **分离 API 与队列 (Split API and Queue)**：API 服务器和队列工作器在不同主机上，可独立扩展。
*   **分布式运行时 (Distributed Runtime)**：用于高并发场景，将编排和执行分离到不同进程。

### 4.4 图加载与编译

部署时，图（Graph）可以以两种方式注册：

1.  **编译后的图 (Compiled Graph)**：推荐方式。服务器在启动时加载一次编译后的图，后续请求直接复用，无编译开销。
2.  **工厂函数 (Factory Function)**：每次请求时调用工厂函数生成图。适用于需要每次运行时动态配置模型或工具的场景，但会增加开销。

### 4.5 运行生命周期

1.  客户端向 API 服务器发送请求，创建待处理运行。
2.  队列工作器获取运行，加载图并执行。
3.  执行过程中，工作器写入检查点并广播流式事件。
4.  API 服务器订阅事件并通过 SSE 转发给客户端。
5.  执行完成后，更新运行状态。

每个工作器可并发执行多个运行（默认 10 个），API 服务器独立扩展，不受工作器并发数限制。

[来源1](https://docs.langchain.com/langsmith/agent-server)

## 5. 生态整合与开发工作流

LangChain 生态通过分层设计，实现了从开发到部署的无缝衔接。

*   **开发阶段**：开发者使用 LangChain 框架层（`create_agent`）或 Deep Agents（`create_deep_agent`）快速构建智能体，利用中间件处理上下文、容错和规划。LangGraph 提供底层控制，用于复杂状态管理和人机协同。
*   **测试与观测**：使用 LangSmith 进行追踪（Tracing）、评估（Evaluation）和调试。LangSmith Engine 可自动检测智能体追踪中的问题并提出修复建议。
*   **部署阶段**：将 LangGraph 图或 LangChain 智能体部署到 LangSmith Agent Server。Agent Server 提供 API 接口、任务队列和持久化存储，支持多模型扩展和高并发处理。
*   **运维阶段**：通过 LangSmith 监控运行状态，收集用户反馈，并通过 CI/CD 管道自动化测试和部署。

这种架构使得团队可以专注于业务逻辑，而将复杂的编排、持久化和运维问题交给 LangChain 生态处理。

[来源1](https://docs.langchain.com/oss/python/langgraph/overview) · [来源2](https://docs.langchain.com/langsmith/agent-server)
