LangChain 结构化输出：让模型返回 JSON

这篇适合谁，读完能做到什么

适合想让智能体返回固定格式数据、而不是自由文本的开发者。读完你能用 response_format 指定输出结构，拿到经过校验的对象或字典，并知道 LangChain 如何在两种策略之间选择。

结构化输出是什么

结构化输出让智能体按预定格式返回数据，常见形式包括 JSON 对象、Pydantic 模型和 dataclass。应用拿到结果后可以直接使用，不必再从自然语言里解析^[1]。在 Python 中，create_agent 会自动处理：模型生成的结构化数据会被捕获、校验，并放在智能体最终状态的 structured_response 键里^[1]。

用 response_format 指定结构

下面的例子定义了一个联系人模型，并把它传给 response_format。直接传入类型时，LangChain 会自动选择策略，结果从 result["structured_response"] 读取^[1]：

from pydantic import BaseModel, Field
from langchain.agents import create_agent


class ContactInfo(BaseModel):
    """Contact information for a person."""
    name: str = Field(description="The name of the person")
    email: str = Field(description="The email address of the person")
    phone: str = Field(description="The phone number of the person")

agent = create_agent(
    model="gpt-6.1-sol",
    response_format=ContactInfo  # Auto-selects ProviderStrategy
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Extract contact info from: John Doe, john@example.com, (555) 123-4567"}]
})

print(result["structured_response"])
# ContactInfo(name='John Doe', email='john@example.com', phone='(555) 123-4567')

两种策略

response_format 可以接受 ToolStrategy、ProviderStrategy、一个模式类型，或者 None^[1]。两种策略的区别如下。

• ProviderStrategy（提供方原生结构化输出）：OpenAI、Anthropic（Claude）、Gemini、xAI（Grok）等提供方原生支持时，它被认为是最可靠的方式^[1]。schema 可以是 Pydantic 模型（返回经过校验的实例）、dataclass、TypedDict，或者 JSON Schema（返回字典，顶层需要有 title 和 description）^[1]。strict 参数用于开启严格遵循 schema，目前 OpenAI 和 xAI 支持它，默认关闭，并且需要 langchain 1.2 及以上版本^[1]。
• ToolStrategy（工具调用）：模型不支持原生结构化输出时，LangChain 用工具调用实现同样的效果，大多数支持工具调用的现代模型都可以使用^[1]。tool_message_content 可以自定义结构化结果对应的工具消息内容；handle_errors 默认开启，可以改成自定义提示、只捕获指定异常类型，或设为 False 让异常直接抛出^[1]。schema 还可以是联合类型，模型会根据上下文选择最合适的一种^[1]。

策略怎么自动选

直接传入模式类型时，只要模型和提供方支持原生结构化输出，LangChain 就使用 ProviderStrategy，否则使用 ToolStrategy^[1]。JSON Schema 字典不会被自动识别，传入时必须用 ProviderStrategy 或 ToolStrategy 明确包装^[1]。

如果模型的能力信息缺失，可以手动声明。langchain 1.1 及以上版本从模型的 profile 数据读取原生支持情况；数据缺失时，可以传入自定义 profile，把 structured_output 设为 True^[1]：

custom_profile = {
    "structured_output": True,
    # ...
}
model = init_chat_model("...", profile=custom_profile)

同时使用工具和结构化输出时，模型必须两者都支持^[1]。dataclass 和 TypedDict 返回的是字典，只有 Pydantic 模型会返回经过校验的对象^[1]。

模型出错时

用工具调用生成结构化数据时，模型可能犯错。例如它同时调用了多个结构化输出工具，智能体会用 ToolMessage 回传错误信息，提示模型重试^[1]。

JavaScript 怎么写

JavaScript 的 createAgent 使用 responseFormat 参数，可以接受 zod schema、任何兼容 Standard Schema 的 schema，或者 JSON Schema 对象。结果放在状态的 structuredResponse 键里^[1]。默认使用工具调用策略，模型支持原生结构化输出时则改用原生方式。想显式指定策略时，用 providerStrategy 或 toolStrategy 包装，二者都从 langchain 导入^[1]。

三种 schema 写法怎么选

Pydantic 模型会做字段校验，返回的是经过校验的实例，适合需要严格类型的场景。dataclass 和 TypedDict 写法更轻，但返回的是字典。直接传入 JSON Schema 时，顶层必须有 title 和 description，并且要包在 ProviderStrategy 或 ToolStrategy 里，否则不会被自动识别^[1]。

严格模式与字段说明

strict 参数会要求结果严格遵循 schema。它目前由 OpenAI 和 xAI 支持，默认关闭；使用时需要 langchain 1.2 或更高版本^[1]。字段上的 description 同样重要。示例中每个字段都写了一句说明，模型依靠这些说明来理解每个字段应当填什么^[1]。

什么时候用工具策略

模型不支持原生结构化输出时，工具策略是通用的替代方案，大多数支持工具调用的现代模型都能用^[1]。handle_errors 默认会捕获校验错误，并使用标准模板提示模型重试^[1]。

读完以后可以检查的几件事

• 模式是 Pydantic 模型、dataclass、TypedDict 还是 JSON Schema，三者返回的类型不同^[1]。
• 结果是从 result["structured_response"] 读取的，而不是从最后一条消息里解析^[1]。
• 如果同时使用工具，模型是否同时支持工具调用和结构化输出^[1]。

运行后拿到的是什么

示例运行后，print 输出的是一个 ContactInfo 实例，字段 name、email 和 phone 的值来自输入文本中的 John Doe、john@example.com 和 (555) 123-4567^[1]。应用可以直接读取这些字段，不必再解析一段自然语言^[1]。

策略选择小结

简单说，直接传入模式类型，让 LangChain 自动选择策略即可；需要明确控制时，再用 ProviderStrategy 或 ToolStrategy 包装。无论哪种策略，结构化结果都放在 structured_response 中，读取方式一致^[1]。

常见问题

• 返回的是字典而不是类实例：这是 dataclass 或 TypedDict 的行为，想要校验过的对象，用 Pydantic 模型^[1]。
• 结构化输出和工具一起用报错：检查模型是否同时支持两者^[1]。
• 想在智能体之外直接得到结构化输出：这属于模型层面的功能，参考模型文档中的结构化输出部分^[1]。

下一步

本文只讲了 create_agent 中的用法。链式调用里如何处理解析错误，也可以参考 LangChain 官方文档中的对应章节^[1]。

本文改编自 LangChain 开源文档中的 Structured output 页面^[1]，原文以 MIT 许可证发布。