> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-docs-zh.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# LangChain v1 新特性

> LangChain v1 是一个专注的、生产就绪的 AI 开发基础框架。 我们围绕三个核心改进简化了框架：

**LangChain v1 是一个专注的、生产就绪的 AI 开发基础框架。** 我们围绕三个核心改进简化了框架：

> [card] [create\_agent](#create_agent)
>
> 构建 LangChain 中智能体的新标准，取代 `langgraph.prebuilt.create_react_agent`。

> [card] [Standard content blocks](#standard-content-blocks)
>
> 一个新的 `content_blocks` 属性，提供跨提供者的现代 LLM 功能的统一访问。

> [card] [Simplified namespace](#simplified-package)
>
> `langchain` 命名空间已简化，专注于智能体所需的基本构建块，遗留功能已移至 `langchain-classic`。

要升级，

```bash pip theme={null}
pip install -U langchain
```

```bash uv theme={null}
uv add langchain
```

有关完整变更列表，请参阅 [迁移指南](https://langchain-docs-zh.mintlify.site/langchain/oss/migrate/langchain-v1.md)。

## `create_agent`

@\[`create_agent`] 是 LangChain 1.0 中构建智能体的标准方式。它比 @\[`langgraph.prebuilt.create_react_agent`]\[create\_react\_agent] 提供更简单的接口，同时通过使用 [中间件](#中间件) 提供更大的定制潜力。

```python theme={null}
from langchain.agents import create_agent

agent = create_agent(
    model="claude-sonnet-4-6",
    tools=[search_web, analyze_data, send_email],
    system_prompt="You are a helpful research assistant."
)

result = agent.invoke({
    "messages": [
        {"role": "user", "content": "Research AI safety trends"}
    ]
})
```

在底层，@\[`create_agent`] 基于基本智能体循环构建——调用模型，让它选择要执行的工具，然后在它不再调用任何工具时结束：

![核心智能体循环图](https://mintcdn.com/langchain-docs-zh/GwyUNaaRzl5kP0v2/langchain/oss/images/core_agent_loop.png?fit=max\&auto=format\&n=GwyUNaaRzl5kP0v2\&q=85\&s=62c5cef860e506ed6212cc2502a302df)

更多信息，请参阅 [智能体](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/agents.md)。

### 中间件

中间件是 @\[`create_agent`] 的定义性特征。它提供了一个高度可定制的入口点，提高了你能构建的内容上限。

优秀的智能体需要 [上下文工程](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/context-engineering.md)：在正确的时间将正确信息传递给模型。中间件帮助你通过可组合的抽象控制动态提示词、对话摘要、选择性工具访问、状态管理和护栏。

#### 预构建的中间件

LangChain 为常见模式提供了一些 [预构建的中间件](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/middleware/built-in.md)，包括：

* @\[`PIIMiddleware`]：在发送给模型之前编辑敏感信息
* @\[`SummarizationMiddleware`]：当对话历史过长时压缩对话历史
* @\[`HumanInTheLoopMiddleware`]：对敏感工具调用要求批准

```python theme={null}
from langchain.agents import create_agent
from langchain.agents.middleware import (
    PIIMiddleware,
    SummarizationMiddleware,
    HumanInTheLoopMiddleware
)


agent = create_agent(
    model="claude-sonnet-4-6",
    tools=[read_email, send_email],
    middleware=[
        PIIMiddleware("email", strategy="redact", apply_to_input=True),
        PIIMiddleware(
            "phone_number",
            detector=(
                r"(?:\+?\d{1,3}[\s.-]?)?"
                r"(?:\(?\d{2,4}\)?[\s.-]?)?"
                r"\d{3,4}[\s.-]?\d{4}"
			),
			strategy="block"
        ),
        SummarizationMiddleware(
            model="claude-sonnet-4-6",
            trigger={"tokens": 500}
        ),
        HumanInTheLoopMiddleware(
            interrupt_on={
                "send_email": {
                    "allowed_decisions": ["approve", "edit", "reject"]
                }
            }
        ),
    ]
)
```

#### 自定义中间件

你也可以构建自定义中间件以满足你的需求。中间件在智能体执行的每个步骤中暴露钩子：

![中间件流程图](https://mintcdn.com/langchain-docs-zh/GwyUNaaRzl5kP0v2/langchain/oss/images/middleware_final.png?fit=max\&auto=format\&n=GwyUNaaRzl5kP0v2\&q=85\&s=b1ebcea2ef7ae760ba826b67f2d5f38f)

通过在 @\[`AgentMiddleware`] 类的子类上实现这些钩子中的任何一种来构建自定义中间件：

| 钩子 | 运行时间 | 用例 |
| - | - | - |
| `before_agent` | 调用智能体之前 | 加载记忆、验证输入 |
| `before_model` | 每次调用 LLM 之前 | 更新提示词、修剪消息 |
| `wrap_model_call` | 每次调用 LLM 时 | 中断并修改请求/响应 |
| `wrap_tool_call` | 每次调用工具时 | 中断并修改工具执行 |
| `after_model` | 每次收到 LLM 响应后 | 验证输出、应用护栏 |
| `after_agent` | 智能体完成后 | 保存结果、清理 |

自定义中间件示例：

```python expandable theme={null}
from dataclasses import dataclass
from typing import Callable

from langchain_openai import ChatOpenAI

from langchain.agents.middleware import (
    AgentMiddleware,
    ModelRequest
)
from langchain.agents.middleware.types import ModelResponse

@dataclass
class Context:
    user_expertise: str = "beginner"

class ExpertiseBasedToolMiddleware(AgentMiddleware):
    def wrap_model_call(
        self,
        request: ModelRequest,
        handler: Callable[[ModelRequest], ModelResponse]
    ) -> ModelResponse:
        user_level = request.runtime.context.user_expertise

        if user_level == "expert":
            # More powerful model
            model = ChatOpenAI(model="gpt-5.5")
            tools = [advanced_search, data_analysis]
        else:
            # Less powerful model
            model = ChatOpenAI(model="gpt-5-nano")
            tools = [simple_search, basic_calculator]

        return handler(request.override(model=model, tools=tools))

agent = create_agent(
    model="claude-sonnet-4-6",
    tools=[
        simple_search,
        advanced_search,
        basic_calculator,
        data_analysis
    ],
    middleware=[ExpertiseBasedToolMiddleware()],
    context_schema=Context
)
```

更多信息，请参阅[完整的中间件指南](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/middleware.md)。

### 基于 LangGraph

由于 @\[`create_agent`] 基于 [LangGraph](https://langchain-docs-zh.mintlify.site/langchain/oss/langgraph.md)构建，您将自动获得对长时间运行和可靠智能体的内置支持，通过：

> [card] Persistence
>
> 对话会话间自动持久化，内置检查点功能

> [card] Streaming
>
> 实时流式输出 Token、工具调用和推理跟踪

> [card] Human-in-the-loop
>
> 在执行敏感操作前暂停智能体运行以供人工审批

> [card] Time travel
>
> 回放对话至任意时间点，并探索替代路径和提示词

您无需学习 LangGraph 即可使用这些功能——它们开箱即用。

### 结构化输出

@\[`create_agent`] 改进了结构化输出生成：

* **主循环集成**：结构化输出现在在主循环中生成，而无需额外的 LLM 调用
* **结构化输出策略**：模型可以在调用工具或使用提供方侧的结构化输出生成之间进行选择
* **成本降低**：消除了额外 LLM 调用的额外费用

```python theme={null}
from langchain.agents import create_agent
from langchain.agents.structured_output import ToolStrategy
from pydantic import BaseModel


class Weather(BaseModel):
    temperature: float
    condition: str

def weather_tool(city: str) -> str:
    """Get the weather for a city."""
    return f"it's sunny and 70 degrees in {city}"

agent = create_agent(
    "gpt-5.4-mini",
    tools=[weather_tool],
    response_format=ToolStrategy(Weather)
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "What's the weather in SF?"}]
})

print(repr(result["structured_response"]))
# results in `Weather(temperature=70.0, condition='sunny')`
```

**错误处理**：通过 `handle_errors` 参数控制错误处理至 `ToolStrategy`：

* **解析错误**：模型生成的数据与期望的结构不匹配
* **多个工具调用**：模型为结构化输出模式生成了 2+ 个工具调用

***

## 标准内容块

> [!NOTE]
>
> 内容块支持目前仅适用于以下集成：
>
> * [`langchain-anthropic`](https://pypi.org/project/langchain-anthropic/)
> * [`langchain-aws`](https://pypi.org/project/langchain-aws/)
> * [`langchain-openai`](https://pypi.org/project/langchain-openai/)
> * [`langchain-google-genai`](https://pypi.org/project/langchain-google-genai/)
> * [`langchain-ollama`](https://pypi.org/project/langchain-ollama/)
>
> 对内容块的支持将逐步扩展到更多提供方。

新的 @\[`content_blocks`]\[BaseMessage(content\_blocks)] 属性引入了跨提供方工作的消息内容标准表示：

```python theme={null}
from langchain_anthropic import ChatAnthropic

model = ChatAnthropic(model="claude-sonnet-4-6")
response = model.invoke("What's the capital of France?")

# Unified access to content blocks
for block in response.content_blocks:
    if block["type"] == "reasoning":
        print(f"Model reasoning: {block['reasoning']}")
    elif block["type"] == "text":
        print(f"Response: {block['text']}")
    elif block["type"] == "tool_call":
        print(f"Tool call: {block['name']}({block['args']})")
```

### 优势

* **提供方无关**：使用相同的 API 无论提供方如何访问推理跟踪、引用、内置工具（网络搜索、代码解释器等）和其他功能
* **类型安全**：所有内容块类型都具有完整的类型提示
* **向后兼容**：标准内容可以 [懒加载](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/messages.md#标准内容块)，因此不会产生相关的破坏性变更

更多信息，请参阅我们的 [内容块](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/messages.md#标准内容块) 指南。

***

## 简化包

LangChain v1 简化了 [`langchain`](https://pypi.org/project/langchain/) 包命名空间，专注于智能体所需的必要构建块。精简的命名空间暴露了最常用和最相关功能：

### 命名空间

| 模块 | 可用内容 | 备注 |
| - | - | - |
| @\[`langchain.agents`] | @\[`create_agent`], @\[`AgentState`] | 核心智能体创建功能 |
| @\[`langchain.messages`] | 消息类型, @\[内容块]\[ContentBlock], @\[`trim_messages`] | 从 @\[`langchain-core`] 重新导出 |
| @\[`langchain.tools`] | @\[`@tool`], @\[`BaseTool`], 注入辅助工具 | 从 @\[`langchain-core`] 重新导出 |
| @\[`langchain.chat_models`] | @\[`init_chat_model`], @\[`BaseChatModel`] | 统一模型初始化 |
| @\[`langchain.embeddings`] | @\[`Embeddings`], @\[`init_embeddings`] | 嵌入模型 |

这些中的大多数是从 `langchain-core` 重新导出的，以提供便利，这为您构建智能体提供了专注的 API 表面。

```python theme={null}
# Agent building
from langchain.agents import create_agent

# Messages and content
from langchain.messages import AIMessage, HumanMessage

# Tools
from langchain.tools import tool

# Model initialization
from langchain.chat_models import init_chat_model
from langchain.embeddings import init_embeddings
```

### `langchain-classic`

遗留功能已迁移至 `langchain-classic` 以保持核心包的精简和专注。

**`langchain-classic` 中包含的内容：**

* 遗留链和链实现
* 检索器（例如 `MultiQueryRetriever` 或来自先前 `langchain.retrievers` 模块的任何内容）
* 修复模型输出错误的输出解析器（例如 `OutputFixingParser`, `RetryOutputParser`）
* 索引 API
* 中心模块（用于程序化管理提示词）
* [`langchain-community`](https://pypi.org/project/langchain-community) 导出
* 其他已弃用的功能

如果您使用任何这些功能，请安装 [`langchain-classic`](https://pypi.org/project/langchain-classic)：

```bash pip theme={null}
pip install langchain-classic
```

```bash uv theme={null}
uv add langchain-classic
```

然后更新您的导入：

```python theme={null}
from langchain import ...  # [!code --]
from langchain_classic import ...  # [!code ++]

from langchain.chains import ...  # [!code --]
from langchain_classic.chains import ...  # [!code ++]

from langchain.retrievers import ...  # [!code --]
from langchain_classic.retrievers import ...  # [!code ++]

from langchain.output_parsers import OutputFixingParser  # [!code --]
from langchain_classic.output_parsers import OutputFixingParser  # [!code ++]

from langchain import hub  # [!code --]
from langchain_classic import hub  # [!code ++]
```

## 迁移指南

查看我们的 [迁移指南](https://langchain-docs-zh.mintlify.site/langchain/oss/migrate/langchain-v1.md) 以获取帮助，将您的代码更新至 LangChain v1。

## 报告问题

请使用 `'v1'` [标签](https://github.com/langchain-ai/langchain/issues?q=state%3Aopen%20label%3Av1) 在 [GitHub](https://github.com/langchain-ai/langchain/issues) 上报告发现的 1.0 版本问题。

## 额外资源

> [card] [LangChain 1.0](https://blog.langchain.com/langchain-langchain-1-0-alpha-releases/)
>
> 阅读公告

> [card] [Middleware guide](https://blog.langchain.com/agent-middleware/)
>
> 深入研究中间件

> [card] [Agents Documentation](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/agents.md)
>
> 完整智能体文档

> [card] [Message Content](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/messages.md#消息内容)
>
> 如何迁移至 LangChain v1

> [card] [Migration guide](https://langchain-docs-zh.mintlify.site/langchain/oss/migrate/langchain-v1.md)
>
> 报告问题或贡献

> [card] [GitHub](https://github.com/langchain-ai/langchain)
>
> 报告问题或贡献

## 参见

* [版本控制](https://langchain-docs-zh.mintlify.site/langchain/oss/versioning.md) – 理解版本号
* [发布策略](https://langchain-docs-zh.mintlify.site/langchain/oss/release-policy.md) – 详细发布策略

***

> 官方原文：[src/oss/python/releases/langchain-v1.mdx](https://github.com/langchain-ai/docs/blob/main/src/oss/python/releases/langchain-v1.mdx) · 非官方翻译，译文由 AI 生成，以英文原文为准。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.