LangChain 核心组件 06：Structured Output

结构化输出我放在 Agents 前面，是因为它本质上是"让模型结果进入程序逻辑"的桥。等这个概念清楚了，再去看 Agent 里的 response_format 就不会突兀。

结构化输出使得智能体能够以特定、可预测的格式返回数据。你无需解析自然语言响应，而是可以直接获取以 JSON 对象、Pydantic 模型或数据类形式呈现的结构化数据，供应用程序直接使用。

LangChain 的create_agent可自动处理结构化输出。用户设置所需的结构化输出模式，当模型生成结构化数据时，该数据会被捕获、验证，并以structured_response为键名返回至智能体状态中。

Python3 点击展开代码

8 lines 展开代码

def create_agent(
    ...
    response_format: Union[
        ToolStrategy[StructuredResponseT],
        ProviderStrategy[StructuredResponseT],
        type[StructuredResponseT],
        None,
    ]

1. 响应格式#

使用response_format控制智能体返回结构化数据的方式：

ToolStrategy[StructuredResponseT]：通过工具调用实现结构化输出
ProviderStrategy[StructuredResponseT]：采用服务提供商原生结构化输出
type[StructuredResponseT]：架构类型 —— 根据模型能力自动选择最优策略
None：未明确请求结构化输出

当直接提供架构类型时，LangChain 会自动选择：

ProviderStrategy（若所选模型及服务提供商支持原生结构化输出，例如 OpenAI、Anthropic (Claude)或xAI (Grok)）。
ToolStrategy（适用于其他所有模型）。

2. Provider strategy#

部分模型提供商通过其 API 原生支持结构化输出（例如 OpenAI、xAI（Grok）、Gemini、Anthropic（Claude））。在可用的情况下，这是最可靠的方法。

要使用此策略，请配置一个ProviderStrategy：

Python3 点击展开代码

3 lines 展开代码

class ProviderStrategy(Generic[SchemaT]):
    schema: type[SchemaT]
    strict: bool | None = None

定义结构化输出格式的模式。支持：

Pydantic 模型：带有字段验证的BaseModel子类，返回经过验证的 Pydantic 实例。
数据类：带有类型注解的 Python 数据类，返回字典。
类型字典：类型化字典类，返回字典。
JSON 模式：包含 JSON 模式规范的字典，返回字典。

下面提供这四种情况的代码

Python3 点击展开代码

21 lines 展开代码

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-5",
    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')

Python3 点击展开代码

23 lines 展开代码

from dataclasses import dataclass
from langchain.agents import create_agent


@dataclass
class ContactInfo:
    """Contact information for a person."""
    name: str # The name of the person
    email: str # The email address of the person
    phone: str # The phone number of the person

agent = create_agent(
    model="gpt-5",
    tools=tools,
    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"}]
})

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

Python3 点击展开代码

22 lines 展开代码

from typing_extensions import TypedDict
from langchain.agents import create_agent


class ContactInfo(TypedDict):
    """Contact information for a person."""
    name: str # The name of the person
    email: str # The email address of the person
    phone: str # The phone number of the person

agent = create_agent(
    model="gpt-5",
    tools=tools,
    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"}]
})

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

Python3 点击展开代码

26 lines 展开代码

from langchain.agents import create_agent


contact_info_schema = {
    "type": "object",
    "description": "Contact information for a person.",
    "properties": {
        "name": {"type": "string", "description": "The name of the person"},
        "email": {"type": "string", "description": "The email address of the person"},
        "phone": {"type": "string", "description": "The phone number of the person"}
    },
    "required": ["name", "email", "phone"]
}

agent = create_agent(
    model="gpt-5",
    tools=tools,
    response_format=ProviderStrategy(contact_info_schema)
)

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

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

3. Tool calling strategy#

对于不支持原生结构化输出的模型，LangChain 会通过工具调用来实现相同的效果。该方法适用于所有支持工具调用的模型（大多数现代模型）。

要使用此策略，请配置ToolStrategy：

Python3 点击展开代码

10 lines 展开代码

class ToolStrategy(Generic[SchemaT]):
    schema: type[SchemaT]
    tool_message_content: str | None
    handle_errors: Union[
        bool,
        str,
        type[Exception],
        tuple[type[Exception], ...],
        Callable[[Exception], str],
    ]

同样，这里的schema模版支持以下：

Pydantic 模型：BaseModel 子类，具备字段校验功能，返回校验后的 Pydantic 实例。
数据类：带有类型注解的 Python 数据类，返回字典。
类型字典：类型化字典类，返回字典。
JSON 模式：符合 JSON 模式规范的字典，返回字典。
联合类型：多种模式选项，模型会根据上下文选择最合适的模式。

这里分别提供五种情况的示例代码：

Python3 点击展开代码

23 lines 展开代码

from pydantic import BaseModel, Field
from typing import Literal
from langchain.agents import create_agent
from langchain.agents.structured_output import ToolStrategy


class ProductReview(BaseModel):
    """Analysis of a product review."""
    rating: int | None = Field(description="The rating of the product", ge=1, le=5)
    sentiment: Literal["positive", "negative"] = Field(description="The sentiment of the review")
    key_points: list[str] = Field(description="The key points of the review. Lowercase, 1-3 words each.")

agent = create_agent(
    model="gpt-5",
    tools=tools,
    response_format=ToolStrategy(ProductReview)
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Analyze this review: 'Great product: 5 out of 5 stars. Fast shipping, but expensive'"}]
})
result["structured_response"]
# ProductReview(rating=5, sentiment='positive', key_points=['fast shipping', 'expensive'])

Python3 点击展开代码

24 lines 展开代码

from dataclasses import dataclass
from typing import Literal
from langchain.agents import create_agent
from langchain.agents.structured_output import ToolStrategy


@dataclass
class ProductReview:
    """Analysis of a product review."""
    rating: int | None  # The rating of the product (1-5)
    sentiment: Literal["positive", "negative"]  # The sentiment of the review
    key_points: list[str]  # The key points of the review

agent = create_agent(
    model="gpt-5",
    tools=tools,
    response_format=ToolStrategy(ProductReview)
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Analyze this review: 'Great product: 5 out of 5 stars. Fast shipping, but expensive'"}]
})
result["structured_response"]
# {'rating': 5, 'sentiment': 'positive', 'key_points': ['fast shipping', 'expensive']}

Python3 点击展开代码

23 lines 展开代码

from typing import Literal
from typing_extensions import TypedDict
from langchain.agents import create_agent
from langchain.agents.structured_output import ToolStrategy


class ProductReview(TypedDict):
    """Analysis of a product review."""
    rating: int | None  # The rating of the product (1-5)
    sentiment: Literal["positive", "negative"]  # The sentiment of the review
    key_points: list[str]  # The key points of the review

agent = create_agent(
    model="gpt-5",
    tools=tools,
    response_format=ToolStrategy(ProductReview)
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Analyze this review: 'Great product: 5 out of 5 stars. Fast shipping, but expensive'"}]
})
result["structured_response"]
# {'rating': 5, 'sentiment': 'positive', 'key_points': ['fast shipping', 'expensive']}

Python3 点击展开代码

39 lines 展开代码

from langchain.agents import create_agent
from langchain.agents.structured_output import ToolStrategy


product_review_schema = {
    "type": "object",
    "description": "Analysis of a product review.",
    "properties": {
        "rating": {
            "type": ["integer", "null"],
            "description": "The rating of the product (1-5)",
            "minimum": 1,
            "maximum": 5
        },
        "sentiment": {
            "type": "string",
            "enum": ["positive", "negative"],
            "description": "The sentiment of the review"
        },
        "key_points": {
            "type": "array",
            "items": {"type": "string"},
            "description": "The key points of the review"
        }
    },
    "required": ["sentiment", "key_points"]
}

agent = create_agent(
    model="gpt-5",
    tools=tools,
    response_format=ToolStrategy(product_review_schema)
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Analyze this review: 'Great product: 5 out of 5 stars. Fast shipping, but expensive'"}]
})
result["structured_response"]
# {'rating': 5, 'sentiment': 'positive', 'key_points': ['fast shipping', 'expensive']}

Python3 点击展开代码

39 lines 展开代码

from langchain.agents import create_agent
from langchain.agents.structured_output import ToolStrategy


product_review_schema = {
    "type": "object",
    "description": "Analysis of a product review.",
    "properties": {
        "rating": {
            "type": ["integer", "null"],
            "description": "The rating of the product (1-5)",
            "minimum": 1,
            "maximum": 5
        },
        "sentiment": {
            "type": "string",
            "enum": ["positive", "negative"],
            "description": "The sentiment of the review"
        },
        "key_points": {
            "type": "array",
            "items": {"type": "string"},
            "description": "The key points of the review"
        }
    },
    "required": ["sentiment", "key_points"]
}

agent = create_agent(
    model="gpt-5",
    tools=tools,
    response_format=ToolStrategy(product_review_schema)
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Analyze this review: 'Great product: 5 out of 5 stars. Fast shipping, but expensive'"}]
})
result["structured_response"]
# {'rating': 5, 'sentiment': 'positive', 'key_points': ['fast shipping', 'expensive']}

4. Custom tool message content#

tool_message_content 参数允许你自定义生成结构化输出时，显示在对话历史中的消息内容。效果如下：

Python3 点击展开代码

24 lines 展开代码

from pydantic import BaseModel, Field
from typing import Literal
from langchain.agents import create_agent
from langchain.agents.structured_output import ToolStrategy


class MeetingAction(BaseModel):
    """Action items extracted from a meeting transcript."""
    task: str = Field(description="The specific task to be completed")
    assignee: str = Field(description="Person responsible for the task")
    priority: Literal["low", "medium", "high"] = Field(description="Priority level")

agent = create_agent(
    model="gpt-5",
    tools=[],
    response_format=ToolStrategy(
        schema=MeetingAction,
        tool_message_content="Action item captured and added to meeting notes!"
    )
)

agent.invoke({
    "messages": [{"role": "user", "content": "From our meeting: Sarah needs to update the project timeline as soon as possible"}]
})

1
================================ Human Message =================================
2

3
From our meeting: Sarah needs to update the project timeline as soon as possible
4
================================== Ai Message ==================================
5
Tool Calls:
6
  MeetingAction (call_1)
7
 Call ID: call_1
8
  Args:
9
    task: Update the project timeline
10
    assignee: Sarah
11
    priority: high
12
================================= Tool Message =================================
13
Name: MeetingAction
14

15
Action item captured and added to meeting notes!

如果没有tool_message_content，最终的ToolMessage会像这样：

1
================================= Tool Message =================================
2
Name: MeetingAction
3

4
Returning structured response: {'task': 'update the project timeline', 'assignee': 'Sarah', 'priority': 'high'}

5. 错误处理#

先skip

1. 响应格式#

2. Provider strategy#

3. Tool calling strategy#

4. Custom tool message content#

5. 错误处理#

LangChain

留言

文章目录