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

# LangChain Python v1.0

<Warning>
  **Alpha 版本提示：** 本文档涵盖的是 **v1-alpha** 版本。内容尚不完整，且可能随时变更。

  如需查阅最新稳定版本，请参阅 v0 版本的 [LangChain Python 文档](https://python.langchain.com/docs/introduction/) 或 [LangChain JavaScript 文档](https://js.langchain.com/docs/introduction/)。
</Warning>

<Note>
  以下包已发布 1.0 Alpha 版本：

  * `langchain`
  * `langchain-core`
  * `langchain-anthropic`
  * `langchain-openai`

  在 Alpha 阶段将逐步扩展对更多包的支持。
</Note>

## <Icon icon="sparkles" /> 新增功能

LangChain 1.0 引入了以下新功能：

* 消息对象新增 `.content_blocks` 属性。该属性提供完全类型化的消息内容视图，并在各提供商之间标准化现代 LLM 功能，包括推理、引用、服务端工具调用等。新消息内容不涉及任何破坏性变更。详情请参阅[消息内容文档](/oss/python/langchain/messages#content)。

* `langchain` 中新增了预构建的 `langgraph` 链和代理。`langchain` 包的接口范围已缩减，聚焦于流行和核心的抽象（例如 `init_chat_model` 和 `init_embeddings`），以及由 `langgraph` 运行时支持的预构建链和代理。为保持向后兼容性，新增了 `langchain-legacy` 包。详情请参阅新的[代理文档](/oss/python/langchain/agents)和[发布说明](https://github.com/langchain-ai/langchain/releases/tag/langchain%3D%3D1.0.0a1)。

## <Icon icon="ban" /> 破坏性变更

<Accordion title="不再支持 Python 3.9" icon="python">
  Python 3.9 将于 2025 年 10 月[停止维护](https://devguide.python.org/versions/)。因此，所有 LangChain 包现在均要求 Python 3.10 或更高版本。
</Accordion>

<Accordion title="部分旧代码迁移至 `langchain-legacy`">
  新版 `langchain` 包缩减了接口范围，专注于 LangChain 组件的标准接口（如 `init_chat_model` 和 `init_embeddings`），以及由 `langgraph` 运行时支持的预构建链和代理。

  此范围之外的现有功能（如索引 API 和 `langchain-community` 功能的导出）已迁移至 `langchain-legacy` 包。

  如需恢复之前的行为，请将 `langchain` 包安装更新为 `langchain-legacy`，并替换导入语句：

  之前：

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

  之后：

  ```python theme={null}
  from langchain_legacy import ...
  ```
</Accordion>

<Accordion title="更新聊天模型的返回类型">
  聊天模型调用的返回类型签名已从 `BaseMessage` 修正为 `AIMessage`。实现 `bind_tools` 的自定义聊天模型应更新其返回签名，以避免类型检查器报错：

  之前：

  ```python theme={null}
  Runnable[LanguageModelInput, BaseMessage]:
  ```

  之后：

  ```python theme={null}
  Runnable[LanguageModelInput, AIMessage]:
  ```
</Accordion>

<Accordion title="OpenAI Responses API 的默认消息格式">
  与 Responses API 交互时，`langchain-openai` 现在默认将响应项存储在消息的 `content` 中。此前需在实例化 `ChatOpenAI` 时指定 `output_version="responses/v1"` 才能启用此行为。此举旨在解决某些多轮对话场景中可能出现的 `BadRequestError`。

  **如需恢复之前的行为**，请将 `LC_OUTPUT_VERSION` 环境变量设置为 `v0`，或在实例化 `ChatOpenAI` 时指定 `output_version="v0"`：

  ```python theme={null}
  os.environ["LC_OUTPUT_VERSION"] = "v0"

  # 或

  from langchain_openai import ChatOpenAI

  llm = ChatOpenA(model="...", output_version="v0")
  ```
</Accordion>

<Accordion title="`langchain-anthropic` 中默认的 `max_tokens`">
  `ChatAnthropic` 中的 `max_tokens` 参数现在将默认为比之前默认值 `1024` 更高的新值。新默认值将根据所选模型而变化。
</Accordion>

<Accordion title="移除已弃用的对象">
  已弃用并计划在 1.0 中移除的方法、函数及其他对象已被删除。
</Accordion>

## <Icon icon="box-archive" /> 弃用项

<Accordion title="`.text()` 现为属性">
  消息对象上的 `.text()` 方法应更新为去掉括号：

  ```python theme={null}
  # 之前
  text = response.text()  # 方法调用

  # 之后
  text = response.text    # 属性访问
  ```

  现有使用方式（即 `.text()`）仍可正常工作，但会发出警告。
</Accordion>

## <Icon icon="robot" /> 预构建代理

**`langchain`** 发布版聚焦于缩减 LangChain 的接口范围，集中于流行和核心的抽象。

### ReAct 代理迁移

**`create_react_agent` 已从 `langgraph.prebuilts` 迁移至 `langchain.agents`**，并进行了重大增强：

**增强的结构化输出**

`create_agent` 改进了将输出强制转换为结构化数据类型的能力：

```python theme={null}
from langchain.agents import create_agent
from langchain_core.messages import HumanMessage
from pydantic import BaseModel

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

def weather_tool(city: str) -> str:
    """获取城市的天气。"""
    return f"{city} 阳光明媚，气温 70 度"

agent = create_agent(
    "openai:gpt-4o-mini",
    tools=[weather_tool],
    response_format=Weather
)
result = agent.invoke({"messages": [HumanMessage("旧金山的天气如何？")]})
print(repr(result["structured_response"]))
#> Weather(temperature=70.0, condition='sunny')
```

**结构改进**

* **主循环集成**：结构化输出现在在主循环中生成，无需额外的 LLM 调用
* **工具/输出选择**：模型可在调用工具、生成结构化输出或两者之间进行选择
* **成本降低**：消除了额外 LLM 调用带来的额外费用

**高级配置**

结构化输出生成的两种策略：

1. **人工工具调用**（大多数模型的默认策略）
   * LangChain 生成与响应格式模式匹配的工具
   * 模型调用这些工具，LangChain 将参数强制转换为所需格式
   * 通过 `ToolStrategy` 提示进行配置

2. **提供商原生实现**
   * 在可用时使用原生结构化输出支持
   * 通过 `ProviderStrategy` 提示进行配置

<Warning>
  **提示输出** 不再通过 `response_format` 参数支持。
</Warning>

### 错误处理

**结构化输出错误**

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

* **解析错误**：模型生成的数据与所需结构不匹配
* **多个工具调用**：模型为结构化输出模式生成 2 个或更多工具调用

**工具调用错误**

更新了工具失败的错误处理：

* **调用失败**：代理返回人工 `ToolMessage`，要求模型重试（保持不变）
* **执行失败**：代理现在默认抛出 `ToolException` 而非重试（防止无限循环）

通过 `ToolNode` 的 `handle_tool_errors` 参数配置行为。

### 破坏性变更

**预绑定模型**

为更好地支持结构化输出，`create_agent` 不再支持预绑定工具或配置的模型：

```python theme={null}
# 不再支持
model_with_tools = ChatOpenAI().bind_tools([some_tool])
agent = create_agent(model_with_tools, tools=[])

# 请改用
agent = create_agent("openai:gpt-4o-mini", tools=[some_tool])
```

<Note>
  如果未使用结构化输出，动态模型函数仍可返回预绑定模型。
</Note>

**导入变更**

```python theme={null}
# 之前
from langgraph.prebuilts import create_agent, ToolNode, AgentState

# 之后
from langchain.agents import create_agent, ToolNode, AgentState
```

## <Icon icon="bullhorn" /> 报告问题

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

## 参见

* [版本控制](/oss/python/versioning) - 理解版本号
* [发布策略](/oss/python/release-policy) - 详细发布策略