在这里插入图片描述

精读 LangChain 官方文档（三）Structured Output 篇：把自然语言回答变成可校验的业务数据

本文基于 LangChain Python 官方文档整理：
Structured Output：https://docs.langchain.com/oss/python/langchain/structured-output
Markdown 版本：https://docs.langchain.com/oss/python/langchain/structured-output.md
对应开源文档编辑入口：
https://github.com/langchain-ai/docs/edit/main/src/oss/langchain/structured-output.mdx

很多 Agent demo 看起来都很顺：用户问一句，模型答一段，页面展示出来。

但一旦进入真实业务，最麻烦的往往不是“模型能不能回答”，而是“回答能不能被系统稳定使用”。

客服系统需要 category、urgency、suggested_reply，风控系统需要 risk_level、reason_codes，会议纪要系统需要 task、assignee、due_date。这些字段要能校验、能入库、能触发后续流程，而不是让工程师从一段自然语言里硬拆 JSON。

这就是 LangChain Structured Output 文档真正要解决的问题。

它不是在讲“怎么让模型输出一个看起来像 JSON 的字符串”，而是在讲：如何在 Agent 运行结构里声明输出契约，让 LangChain 自动选择结构化策略、校验结果，并把最终数据放进 Agent state 的 structured_response。

这篇文档的核心主线可以概括成一句话：

Structured Output = Schema Contract + Strategy Selection + Validation Feedback。

也就是说，LangChain 的 Agent 层结构化输出主要解决三件事：

  • Schema Contract：用 Pydantic、Dataclass、TypedDict 或 JSON Schema 声明你要什么数据。
  • Strategy Selection：根据模型能力选择 Provider 原生结构化输出，或者退回 Tool Calling 策略。
  • Validation Feedback：当模型输出不符合结构时，通过错误反馈和重试把结果拉回契约。

下面这张图先把主线串起来：

结构化输出主线图

图里可以重点看这条链路：

Business Need -> Schema -> response_format -> Strategy -> structured_response

理解这条链路后，ProviderStrategy、ToolStrategy、handle_errors、structured_response 就不会再是分散参数，而是同一个“可校验输出契约”的不同环节。



1. Structured Output（结构化输出）：它到底解决什么问题

它解决的问题：
Structured Output 解决的是“Agent 的最终结果如何被程序稳定消费”，而不是只解决“模型如何生成 JSON”。

官方文档强调，结构化输出允许 Agent 以特定、可预测的格式返回数据。这样应用不需要从自然语言里解析内容，而是可以直接拿到 JSON 对象、Pydantic 模型实例、Dataclass 或字典。

在 Agent 场景里，这个能力尤其关键。因为 Agent 往往不是只回答一句话，它可能经过工具调用、状态更新、错误重试，最后才产出结果。结构化输出的价值，是让最终结果成为系统可依赖的数据对象。

示例：

import os

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


class CustomerTicket(BaseModel):
    """客服工单结构化结果。"""

    category: str = Field(description="工单类别，例如物流、退款、破损、改地址")
    urgency: str = Field(description="紧急程度，例如低、中、高")
    user_intent: str = Field(description="用户最核心的诉求")
    suggested_reply: str = Field(description="建议回复给用户的话")


model = ChatOpenAI(
    model="qwen3.7-max",
    api_key=os.environ["QWEN_API_KEY"],
    base_url=os.environ["QWEN_BASE_URL"],
)

agent = create_agent(
    model=model,
    tools=[],
    response_format=CustomerTicket,
)

result = agent.invoke({
    "messages": [
        {
            "role": "user",
            "content": "用户说：蛋糕收到时已经压坏了，今天生日会要用，现在很着急。",
        }
    ]
})

print(result["structured_response"])

这里：

  • CustomerTicket：业务需要的结构化输出 schema，用来定义 Agent 最终要返回哪些字段。
  • category：工单类别字段，方便后续派单、筛选和统计。
  • urgency：紧急程度字段，方便系统决定优先级。
  • user_intent：用户意图字段，帮助客服快速理解核心诉求。
  • suggested_reply：建议回复字段，可以直接展示给人工客服审核。
  • response_format：create_agent 的结构化输出入口，告诉 Agent 最终结果应该符合什么结构。
  • structured_response：Agent 最终 state 里的结构化结果键。

业务场景：
在客服、质检、法务审核、投标文档分析等场景里，系统不能只拿一段“看起来不错”的回答。它需要字段明确、类型稳定、可校验、可入库的数据。

最简记法：

结构化输出不是美化回答，而是把 Agent 结果变成系统数据。


2. Agent State（智能体状态）：结果最终落到 structured_response

它解决的问题：
Agent state 解决的是“结构化结果最终在哪里取”，避免开发者在消息历史里到处找答案。

官方文档说明，create_agent 会自动处理结构化输出。开发者设置想要的输出 schema 后，当模型生成结构化数据时，LangChain 会捕获、校验，并把它放到 Agent 最终 state 的 structured_response 键里。

示例：

final_state = agent.invoke({
    "messages": [
        {"role": "user", "content": "请把这段客户反馈整理成客服工单。"}
    ]
})

ticket = final_state["structured_response"]
print(ticket.category)
print(ticket.urgency)

这里：

  • final_state：Agent 执行结束后的状态对象，里面既可能有消息，也可能有结构化结果。
  • messages：Agent 运行过程中的消息列表，适合做追踪和调试。
  • structured_response：最终结构化结果，适合给业务系统消费。
  • ticket.category：如果 schema 是 Pydantic 模型，结果通常可以像对象属性一样读取。

业务场景：
一个后台工单系统不应该扫描 messages 里最后一条文本，再尝试 json.loads()。更稳定的方式是直接读取 structured_response，把它交给数据库、表单或审核流。

最简记法：

消息记录给人和调试看，structured_response 给业务系统用。

Agent状态落点图



3. response_format（响应格式）：结构化输出的总开关

它解决的问题：
response_format 解决的是“开发者如何声明 Agent 的输出契约”。

官方文档里，create_agent 的 response_format 支持四种形式：

  • ToolStrategy[StructuredResponseT]：用工具调用实现结构化输出。
  • ProviderStrategy[StructuredResponseT]：使用模型供应商原生结构化输出能力。
  • type[StructuredResponseT]：直接传 schema 类型，让 LangChain 自动选择策略。
  • None：不显式要求结构化输出。

示例：

from langchain.agents.structured_output import ProviderStrategy, ToolStrategy

# 方式一：直接传 schema，让 LangChain 自动选择策略
agent_auto = create_agent(
    model=model,
    tools=[],
    response_format=CustomerTicket,
)

# 方式二：明确使用供应商原生结构化输出策略
agent_provider = create_agent(
    model=model,
    tools=[],
    response_format=ProviderStrategy(CustomerTicket),
)

# 方式三：明确使用工具调用策略
agent_tool = create_agent(
    model=model,
    tools=[],
    response_format=ToolStrategy(CustomerTicket),
)

这里：

  • response_format=CustomerTicket：最常用写法，LangChain 根据模型能力自动选策略。
  • ProviderStrategy(CustomerTicket)：显式要求走供应商原生结构化输出。
  • ToolStrategy(CustomerTicket)：显式要求走工具调用形式的结构化输出。
  • None：表示不需要 Agent 返回结构化结果。

业务场景：
如果团队只想先跑通业务，直接传 schema 是最省心的。等到上线前需要明确控制供应商能力、兼容模型或错误处理策略，再显式使用 ProviderStrategy 或 ToolStrategy。

最简记法：

response_format 是 Agent 输出契约的入口。

response_format策略选择图



4. Schema Types（结构定义）：Pydantic、Dataclass、TypedDict、JSON Schema 怎么选

它解决的问题：
Schema types 解决的是“结构化结果的字段、类型和说明应该用什么形式表达”。

官方文档说明，ProviderStrategy 支持 Pydantic、Dataclass、TypedDict 和 JSON Schema。ToolStrategy 也支持这些形式，并额外支持 Union types，让模型在多个结构之间选择最合适的一种。

示例：

from typing import Literal, TypedDict


class RefundDecision(TypedDict):
    """退款审核结构化结果。"""

    order_id: str
    decision: Literal["同意退款", "拒绝退款", "需要人工审核"]
    reason: str


agent = create_agent(
    model=model,
    tools=[],
    response_format=RefundDecision,
)

这里：

  • TypedDict：Python 类型字典，适合轻量声明字段结构。
  • order_id：订单编号字段，用来和业务订单表关联。
  • decision：审核结论字段，用 Literal 限制可选值。
  • reason：决策原因字段，解释为什么给出这个结论。
  • Literal：限制字段只能取一组固定值，减少模型自由发挥。

业务场景：
如果结果要做严格校验和复杂字段说明，Pydantic 更合适；如果团队只是需要轻量类型提示，TypedDict 也够用；如果要和已有 API 契约对齐，JSON Schema 可能更自然。

最简记法：

Schema 不是写给模型看的装饰，而是写给系统执行的数据合同。


5. Provider Strategy（供应商原生策略）：让模型 API 直接约束输出

它解决的问题：
ProviderStrategy 解决的是“当模型供应商原生支持结构化输出时，如何获得更高可靠性”。

官方文档说明，一些模型供应商支持通过 API 原生约束结构化输出。使用这种方式时，供应商会在模型侧执行 schema 约束，因此通常比单纯提示词更可靠。

示例：

from langchain.agents.structured_output import ProviderStrategy

agent = create_agent(
    model=model,
    tools=[],
    response_format=ProviderStrategy(CustomerTicket),
)

result = agent.invoke({
    "messages": [
        {"role": "user", "content": "请从客户反馈中抽取工单类别、紧急程度和建议回复。"}
    ]
})

ticket = result["structured_response"]

这里：

  • ProviderStrategy：供应商原生结构化输出策略。
  • schema：策略内部的必填参数，表示目标结构。
  • strict：可选参数，用来启用更严格的 schema adherence；官方文档说明它需要 langchain>=1.2，且取决于供应商支持。
  • ticket：经过 schema 校验后的结构化结果。

业务场景：
如果你要把 AI 结果直接写入数据库，或者让它触发后续自动化流程，优先使用原生结构化输出更稳。比如投诉升级、合同条款抽取、发票字段识别，都不适合只靠“请输出 JSON”。

最简记法：

ProviderStrategy 是让供应商 API 帮你守住结构。

ProviderStrategy原生约束图



6. Automatic Strategy（自动策略选择）：直接传 schema 时 LangChain 怎么判断

它解决的问题：
自动策略选择解决的是“开发者不想手动判断模型能力时，LangChain 如何选择实现路径”。

官方文档说明，当你直接把 schema 类型传给 response_format 时，LangChain 会自动选择：

  • 如果模型和供应商支持原生结构化输出，使用 ProviderStrategy。
  • 否则使用 ToolStrategy。

对于 langchain>=1.1，原生结构化输出能力会动态读取模型的 profile 数据。如果 profile 数据不可用，也可以手动指定或改用明确策略。

示例：

from langchain.chat_models import init_chat_model

custom_profile = {
    "structured_output": True,
    "tool_calling": True,
}

profiled_model = init_chat_model(
    model="qwen3.7-max",
    model_provider="openai",
    api_key=os.environ["QWEN_API_KEY"],
    base_url=os.environ["QWEN_BASE_URL"],
    profile=custom_profile,
)

agent = create_agent(
    model=profiled_model,
    tools=[],
    response_format=CustomerTicket,
)

这里：

  • init_chat_model：LangChain 的通用模型初始化函数。
  • profile：模型能力画像，用来告诉 LangChain 模型支持哪些能力。
  • structured_output：表示模型是否支持原生结构化输出。
  • tool_calling：表示模型是否支持工具调用。
  • model_provider：供应商标识，这里按 OpenAI-compatible 接口连接。

业务场景：
企业内部经常会接入兼容 OpenAI 协议的模型网关。网关背后的模型能力不一定能被 LangChain 自动识别，这时补充 profile 可以减少误判，让策略选择更符合实际。

最简记法：

直接传 schema 是省心入口，profile 是模型能力的说明书。


7. Tool Strategy（工具调用策略）：把结构化输出伪装成一次工具调用

它解决的问题：
ToolStrategy 解决的是“模型不支持原生结构化输出时，如何依然拿到可校验结果”。

官方文档说明，对于不支持原生结构化输出的模型，LangChain 会使用工具调用实现同样目标。只要模型支持 tool calling，就可以把 schema 变成一个“结构化输出工具”，让模型以工具参数的形式提交结果。

示例：

from typing import Literal

from langchain.agents.structured_output import ToolStrategy


class ProductReview(BaseModel):
    """商品评论分析结果。"""

    rating: int | None = Field(description="评分，范围为 1 到 5", ge=1, le=5)
    sentiment: Literal["正向", "负向", "中性"] = Field(description="评论情绪")
    key_points: list[str] = Field(description="评论要点，使用 1 到 3 个短语")


agent = create_agent(
    model=model,
    tools=[],
    response_format=ToolStrategy(ProductReview),
)

result = agent.invoke({
    "messages": [
        {"role": "user", "content": "分析这条评论：包装很好，物流很快，但是价格有点贵。"}
    ]
})

print(result["structured_response"])

这里：

  • ToolStrategy：通过工具调用实现结构化输出的策略。
  • schema：目标结构，必填。
  • rating：评分字段，ge=1 和 le=5 分别表示最小值和最大值约束。
  • sentiment：情绪字段，使用 Literal 限制可选值。
  • key_points：评论要点字段，类型是字符串列表。

业务场景：
很多兼容模型首先支持的是工具调用，而不是供应商原生结构化输出。对于评论分析、线索打分、会议事项抽取这类任务，ToolStrategy 是非常实用的兜底方案。

最简记法：

ToolStrategy 是用工具调用通道交付结构化结果。

ToolStrategy工具通道图



8. tool_message_content（工具消息内容）：控制对话历史里的结构化回执

它解决的问题：
tool_message_content 解决的是“结构化输出完成后，工具消息在对话历史里显示什么”。

官方文档说明，使用 ToolStrategy 时，可以自定义结构化输出生成后的 ToolMessage 内容。如果不设置，默认会在工具消息里显示结构化响应数据。

示例：

from typing import Literal


class MeetingAction(BaseModel):
    """会议待办事项。"""

    task: str = Field(description="需要完成的具体任务")
    assignee: str = Field(description="任务负责人")
    priority: Literal["低", "中", "高"] = Field(description="任务优先级")


agent = create_agent(
    model=model,
    tools=[],
    response_format=ToolStrategy(
        schema=MeetingAction,
        tool_message_content="已提取会议待办，并写入结构化结果。",
    ),
)

agent.invoke({
    "messages": [
        {"role": "user", "content": "会议记录：小王本周五前更新项目排期，优先级高。"}
    ]
})

这里：

  • MeetingAction：会议待办的结构化 schema。
  • task：任务内容字段。
  • assignee：负责人字段。
  • priority：优先级字段。
  • tool_message_content：结构化输出工具完成后写入对话历史的消息内容。
  • ToolMessage：工具调用完成后的消息类型，常用于记录工具执行结果。

业务场景：
如果对话历史会被展示给用户或写入审计日志，你可能不希望工具消息里塞完整结构化数据，而是显示一句更友好的回执。真正的数据仍然从 structured_response 读取。

最简记法：

tool_message_content 管历史消息怎么写，不改变最终 structured_response。

工具消息回执图



9. Union Types（联合结构）：让模型在多个结构里选一个

它解决的问题：
Union types 解决的是“同一段输入可能对应不同业务对象时，如何让 Agent 选择最合适的结构”。

官方文档说明，ToolStrategy 支持 Union types。也就是说，你可以给出多个 schema，模型根据上下文选择最匹配的一种。

示例：

from typing import Union


class ContactInfo(BaseModel):
    """联系人信息。"""

    name: str = Field(description="联系人姓名")
    email: str = Field(description="联系人邮箱")


class EventDetails(BaseModel):
    """活动信息。"""

    event_name: str = Field(description="活动名称")
    date: str = Field(description="活动日期")


agent = create_agent(
    model=model,
    tools=[],
    response_format=ToolStrategy(Union[ContactInfo, EventDetails]),
)

result = agent.invoke({
    "messages": [
        {"role": "user", "content": "请抽取信息：张三负责 7 月 18 日的新品发布会。"}
    ]
})

这里：

  • Union[ContactInfo, EventDetails]：表示结构化结果可以是联系人信息，也可以是活动信息。
  • ContactInfo：联系人结构。
  • EventDetails：活动结构。
  • event_name：活动名称字段。
  • date：活动日期字段。

业务场景：
一个企业助手可能同时处理名片识别、会议安排、合同条款、售后工单。Union 能让同一个入口根据输入选择不同结构，但也要注意边界清晰，否则模型可能同时命中多个结构。

最简记法：

Union 适合多对象入口，但结构边界要足够清楚。


10. Multiple Structured Outputs Error（多个结构化输出错误）：一次只应该交付一个最终结构

它解决的问题：
多个结构化输出错误解决的是“模型一次返回多个结构化工具调用时，Agent 如何纠偏”。

官方文档给出的典型情况是：你用 Union 提供多个 schema，模型却同时调用了两个结构化输出工具。LangChain 会通过 ToolMessage 给出错误反馈，提示模型修正为一个结构化响应。

示例：

agent = create_agent(
    model=model,
    tools=[],
    response_format=ToolStrategy(Union[ContactInfo, EventDetails]),
)

result = agent.invoke({
    "messages": [
        {
            "role": "user",
            "content": "请抽取主要信息：李雷用 lilei@example.com 报名了 8 月 1 日的技术沙龙。",
        }
    ]
})

structured = result["structured_response"]

这里：

  • MultipleStructuredOutputsError：模型返回多个结构化输出时对应的错误类型。
  • ToolMessage：LangChain 用来反馈错误并要求模型修正的消息。
  • structured：最终被修正后的一个结构化结果。
  • Union：多个 schema 的选择入口，也是最容易出现多结果歧义的位置。

业务场景：
如果一个输入里同时包含联系人和活动信息，系统要提前决定“这次任务到底抽取哪个对象”。如果业务真正需要两个对象，就不要把它伪装成单一 Union 输出，而应该设计一个包含 contacts 和 events 的聚合 schema。

最简记法：

一次结构化输出最好对应一个明确业务对象。

结构化错误重试图



11. Schema Validation Error（结构校验错误）：字段不合格时让模型重试

它解决的问题：
结构校验错误解决的是“模型返回了结构，但字段值不满足约束时怎么办”。

官方文档说明，当结构化输出不符合预期 schema 时，Agent 会提供具体错误反馈。比如字段 rating 要求在 1 到 5 之间，模型却返回 10，LangChain 会把校验错误反馈给模型，让它修正。

示例：

class ProductRating(BaseModel):
    """商品评分结构。"""

    rating: int | None = Field(description="评分，范围为 1 到 5", ge=1, le=5)
    comment: str = Field(description="评论内容")


agent = create_agent(
    model=model,
    tools=[],
    response_format=ToolStrategy(ProductRating),
    system_prompt="你是一名商品评论分析助手。不要编造字段或数值。",
)

result = agent.invoke({
    "messages": [
        {"role": "user", "content": "解析这条评论：这个产品太棒了，我给 10 分。"}
    ]
})

这里：

  • ge=1：字段值必须大于等于 1。
  • le=5：字段值必须小于等于 5。
  • SchemaValidationError：结构化结果不满足 schema 约束时对应的错误。
  • system_prompt：系统提示词，这里提醒模型不要编造字段或数值。
  • handle_errors=True：ToolStrategy 默认会处理错误并尝试重试。

业务场景：
评分、金额、日期、枚举状态这类字段不应该“差不多就行”。如果字段超出范围，后续数据库约束、统计报表和自动化流程都会出问题。结构化输出的校验层，就是把这些问题尽早拦住。

最简记法：

Schema 校验不是挑剔模型，而是在保护后续系统。


12. handle_errors（错误处理策略）：决定哪些错误要自动修复

它解决的问题：
handle_errors 解决的是“结构化输出失败时，是自动重试、定制提示，还是直接抛错”。

官方文档列出了几种策略：

  • True：捕获所有错误，并使用默认错误模板，默认值就是这个。
  • str：捕获所有错误，但使用自定义错误消息。
  • type[Exception]：只捕获指定异常类型。
  • tuple[type[Exception], ...]：只捕获指定的一组异常类型。
  • Callable[[Exception], str]：用自定义函数生成错误消息。
  • False：不重试，直接让异常抛出。

示例：

from langchain.agents.structured_output import (
    MultipleStructuredOutputsError,
    StructuredOutputValidationError,
)


# 根据结构化输出错误类型生成给模型看的修正提示。
def custom_error_handler(error: Exception) -> str:
    if isinstance(error, StructuredOutputValidationError):
        return "字段格式不符合要求，请按 schema 重新输出。"
    if isinstance(error, MultipleStructuredOutputsError):
        return "你返回了多个结构化结果，请只保留最符合任务目标的一个。"
    return f"结构化输出失败：{error}"


agent = create_agent(
    model=model,
    tools=[],
    response_format=ToolStrategy(
        schema=ProductRating,
        handle_errors=custom_error_handler,
    ),
)

这里：

  • handle_errors：控制结构化输出错误如何处理。
  • StructuredOutputValidationError：字段类型、范围或格式校验失败。
  • MultipleStructuredOutputsError：模型返回了多个结构化输出。
  • custom_error_handler：自定义错误处理函数，返回值会作为反馈消息给模型。
  • handle_errors=False：适合你希望失败立刻暴露给上层业务，而不是让模型继续重试的场景。

业务场景：
客服摘要可以自动重试，用户几乎感受不到；金融风控、合规审核、合同条款识别这类高风险场景，可能更适合限制重试次数、记录错误、转人工，而不是悄悄修正。

最简记法：

handle_errors 决定结构化失败时，是让模型再试一次，还是让系统接管。


13. Tools + Structured Output（工具与结构化输出共存）：模型能力要同时支持两条通道

它解决的问题：
工具与结构化输出共存解决的是“Agent 既要调用业务工具，又要返回结构化结果时，模型能力是否够用”。

官方文档提醒，如果同时指定普通工具和结构化输出，模型必须支持工具调用与结构化输出的同时使用。这个细节非常工程化，因为真实 Agent 往往既要查系统，又要产出结构化结果。

示例：

from langchain.tools import tool


# 查询订单状态，供 Agent 在生成结构化客服工单前获取真实业务信息。
@tool
def get_order_status(order_id: str) -> str:
    """根据订单编号查询订单状态。"""
    return f"订单 {order_id} 当前状态：配送中，预计明天送达。"


agent = create_agent(
    model=model,
    tools=[get_order_status],
    response_format=CustomerTicket,
    system_prompt="你是一名客服助手。涉及订单状态时，先查询工具，再整理结构化工单。",
)

result = agent.invoke({
    "messages": [
        {"role": "user", "content": "订单 A10086 还没到，客户很着急，请整理工单。"}
    ]
})

这里：

  • tools：Agent 可调用的普通业务工具列表。
  • get_order_status：订单查询工具函数。
  • order_id：订单编号参数。
  • response_format：最终结构化输出契约。
  • system_prompt：约束 Agent 先查询真实业务信息，再生成结构化结果。

业务场景：
在售后系统里，Agent 不能凭空判断物流状态。它需要先调用订单工具，再把结果整理成 CustomerTicket。这要求模型既能走工具调用链路，又能完成结构化返回。

最简记法：

真实 Agent 往往先用工具拿事实，再用结构化输出交付结果。

业务系统集成图



14. Production Design（生产设计）：结构化输出不是最后一步，而是系统边界

它解决的问题：
生产设计解决的是“拿到 structured_response 以后，业务系统如何继续安全运行”。

结构化输出让 Agent 结果更稳定，但它不等于完整的业务闭环。上线时还需要继续考虑：

  • 字段是否能直接映射到数据库列。
  • 枚举值是否和业务系统状态码一致。
  • 日期、金额、手机号、邮箱等字段是否需要二次校验。
  • AI 结果是否需要人工审核。
  • 结构化失败是否要进入异常队列。
  • 每次结构化输出是否要记录原始输入、schema 版本和模型版本。

示例：

ticket = result["structured_response"]

record = {
    "category": ticket.category,
    "urgency": ticket.urgency,
    "user_intent": ticket.user_intent,
    "suggested_reply": ticket.suggested_reply,
    "schema_version": "customer_ticket_v1",
    "model_name": "qwen3.7-max",
}

这里：

  • record：准备写入业务系统的数据字典。
  • schema_version：结构版本号，方便后续字段变更和数据追溯。
  • model_name：模型名称，方便排查输出质量和成本。
  • category / urgency / user_intent / suggested_reply：来自结构化结果的业务字段。

业务场景：
如果结构化输出用于自动派单，最好让 category 对齐内部工单分类表；如果用于法务审查，最好保留原始文本和模型版本；如果用于用户可见回复，最好增加人工审核或置信度策略。

最简记法：

Structured Output 是 AI 和业务系统之间的数据边界。


总结：Structured Output 篇真正讲的是 Agent 输出契约

如果把 LangChain Structured Output 文档压缩成一张心智表，可以这样理解：

模块 作用
response_format 在 create_agent 中声明结构化输出契约
structured_response Agent 最终 state 中的结构化结果
ProviderStrategy 使用供应商原生结构化输出能力
ToolStrategy 用工具调用实现结构化输出
schema 定义字段、类型、约束和说明
Pydantic 适合严格字段校验和丰富说明
Dataclass 适合 Python 数据对象风格
TypedDict 适合轻量字典结构
JSON Schema 适合和已有 API 契约对齐
Union 让模型在多个结构中选择一种
tool_message_content 控制工具消息在历史记录中的显示内容
handle_errors 控制结构化失败后的重试和错误反馈
StructuredOutputValidationError 字段校验失败
MultipleStructuredOutputsError 模型返回多个结构化结果
profile 描述模型是否支持结构化输出和工具调用

一句话总结：

LangChain 的 Structured Output，是把 Agent 的自然语言能力收束成可校验、可追踪、可交付给业务系统的数据契约。

学习时可以把它分成三层：

第一层：声明契约
schema / response_format / Pydantic / TypedDict / JSON Schema

第二层：选择策略
ProviderStrategy / ToolStrategy / profile / strict

第三层：处理失败
structured_response / ToolMessage / handle_errors / validation retry

理解这一层后，再读 Streaming、Event Streaming、Messages、Tools 和 Runtime 时，会更容易看到 LangChain 的 Agent 工程主线：模型不是只负责“说话”，它还要在可控结构里和程序系统交接。

Logo
AI硬件创业社区

智能硬件社区聚焦AI智能硬件技术生态，汇聚嵌入式AI、物联网硬件开发者，打造交流分享平台，同步全国赛事资讯、开展 OPC 核心人才招募，助力技术落地与开发者成长。

更多推荐

如何高效解决数据导出难题：NocoDB终极实战指南

你是否曾为数据库数据导出格式单一、操作复杂而烦恼？NocoDB作为一款开源免费的Airtable替代方案，提供了强大的数据导出功能，让你在3分钟内掌握专业级数据导出技巧。本文将为你深入解析NocoDB的CSV和JSON导出功能，通过实战配置和高级技巧，彻底解决数据迁移、备份与共享的痛点。## 数据导出痛点与NocoDB解决方案### 常见数据导出难题- **格式限制**：传统工具仅支持基

avatar AI硬件创业社区

终极解决方案：无VR设备也能畅玩《半条命：Alyx》的完整指南

还在为没有昂贵的VR设备而无法体验《半条命：Alyx》这款VR独占大作而烦恼吗？HLA-NoVR模组为你提供了完美的解决方案！这个革命性的非VR转换模组通过精妙的脚本设计，将原本依赖VR设备的交互体验完美转换为键盘鼠标操作，让普通PC玩家也能享受到这款经典游戏的完整魅力。HLA-NoVR是目前最简单易用且功能最全面的非VR模组，让你无需VR设备就能体验《半条命：Alyx》的全部内容。## 🎮

avatar AI硬件创业社区

ComfyUI-WanVideoWrapper：5分钟掌握AI视频生成全流程

在AI视频生成技术飞速发展的今天，ComfyUI-WanVideoWrapper为创作者提供了一个强大而直观的解决方案。这个开源项目将WanVideo模型的先进功能与ComfyUI的可视化工作流完美结合，让你能够轻松实现从文本到视频、从图像到视频的创意转换。无论你是数字艺术爱好者还是专业内容创作者，都能在这里找到适合自己的AI视频生成工具。## 快速开始：安装与配置### 环境要求开始之

avatar AI硬件创业社区