LangChain structured output怎样把工具结果映射到数据模型

我第一次把 LangChain 工具接到业务代码时，最容易混淆的是两件事：工具函数返回了一个字典，并不等于 Agent 已经返回了一个可以放心交给业务层的数据模型。更稳妥的做法是把工具结果当作中间消息，再用结构化输出策略把最终响应收敛到明确的 schema。

官方文档：https://docs.langchain.com/oss/python/langchain/structured-output

如果目标是“工具查数据，Agent 返回固定字段”，就让工具负责取数和报错，让 ToolStrategy 或提供商原生策略负责最终模型；不要把未经约束的工具字符串直接当成业务对象。

下面的示例使用 LangChain 当前文档中的 create_agent、ToolStrategy 和 Pydantic 模型。代码是结构化示例，图中的关系也是静态说明图，不代表已经在本机执行。

先把工具返回值和最终模型分开

LangChain 文档把 structured output 定义为可预测的 JSON、Pydantic 模型或 dataclass。Agent 的最终状态会在 structured_response 字段中给出结构化结果；工具本身则先返回工具消息。这个分层很重要：工具知道“查到了什么”，模型 schema 约束“业务代码最终接收什么”。

因此，映射链路可以简单记成：tool return -> ToolMessage -> agent state -> structured_response。不要把中间的工具返回字典直接当作最终的 OrderSummary；最终字段是否完整、类型是否正确，应该由 schema 和错误处理策略共同决定。

为工具结果定义稳定的数据模型

先定义模型，再设计工具的返回值。下面的模型只保留订单摘要需要的字段，工具返回值也使用同名键，减少后续转换的隐式规则。

from pydantic import BaseModel, Field
from langchain.tools import tool


class OrderSummary(BaseModel):
    """业务层真正需要的订单摘要。"""

    order_id: str = Field(description="订单编号")
    total: float = Field(description="订单总额")
    currency: str = Field(description="金额币种")


@tool
def lookup_order(order_id: str) -> dict:
    """按订单编号查询摘要，返回可映射到 OrderSummary 的字段。"""
    # 这里用固定数据演示边界；真实项目应在此处理数据库异常和权限。
    if order_id != "A-1001":
        raise ValueError("订单不存在")
    return {
        "order_id": order_id,
        "total": 128.5,
        "currency": "CNY",
    }

这里的关键不是让工具“直接返回 Pydantic 对象”，而是让工具输出一个稳定、最小且不带敏感字段的业务结果。工具若返回内部数据库整行记录，模型可能看到不必要的信息，也会让 schema 失去边界意义。

用 ToolStrategy 接住工具结果

当模型不提供原生 structured output 时，LangChain 可以用工具调用策略实现相同目标。将 OrderSummary 包在 ToolStrategy 中，Agent 就有了明确的最终输出契约；调用完成后，从状态的 structured_response 取模型，而不是从普通文本里二次猜字段。

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


agent = create_agent(
    model="your-chat-model",
    tools=[lookup_order],
    response_format=ToolStrategy(OrderSummary),
)

result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "查询订单 A-1001，并返回订单摘要。",
    }]
})

# 业务层只接收 schema 约束后的最终对象。
summary = result["structured_response"]
print(summary.order_id, summary.total, summary.currency)

如果模型和提供商支持原生结构化输出，也可以让 LangChain 自动选择 ProviderStrategy。无论走哪条策略，业务代码都应固定读取结构化响应；不要因为某个模型当前能稳定输出 JSON，就省略最后的类型边界。

把缺字段、工具异常和敏感信息留在边界内

实践中最麻烦的不是正常字段，而是异常路径。工具查询不到订单时，应返回清晰的工具错误；工具成功但缺少 currency 时，应让 schema 暴露问题，而不是在业务层用默认值悄悄掩盖。LangChain 的 ToolStrategy 提供 handle_errors 配置，可以决定结构化输出失败时是否生成错误提示并重试。

from langchain.agents.structured_output import ToolStrategy


def keep_error_message(error: Exception) -> str:
    """只把可行动的错误原因交给模型，避免泄露内部细节。"""
    # 生产环境不要把 SQL、令牌或内部堆栈放进模型可见消息。
    if isinstance(error, ValueError):
        return f"工具结果无法映射：{error}。请说明缺少的业务条件。"
    return "工具暂时不可用，请不要猜测订单数据。"


agent = create_agent(
    model="your-chat-model",
    tools=[lookup_order],
    response_format=ToolStrategy(
        OrderSummary,
        handle_errors=keep_error_message,
    ),
)

我会把边界检查分成三层：工具层过滤权限和敏感字段；schema 层约束类型、必填项和字段含义；业务层只消费 structured_response，并记录工具调用是否成功。这样即使模型换了，业务接口也不会跟着普通文本格式一起漂移。

实际接入时记住这三个判断

• 工具结果是中间数据，最终模型来自结构化输出策略；两者不要混用。
• schema 字段尽量贴近业务对象，工具返回最小必要字段，避免把内部记录整包暴露给模型。
• 缺字段和工具异常要有明确路径；遇到未知错误时让模型说明暂不可用，不要猜测结果。

如果你只是想让一个模型直接输出 JSON，可以从提供商原生策略开始；只要流程中包含工具调用，就要额外确认模型是否支持同时使用 tools 和 structured output。最重要的验收点不是“文本看起来像 JSON”，而是业务代码能稳定从 structured_response 取到约定的数据模型。

相关问题

工具返回字符串还能做结构化输出吗？可以，但字段映射更依赖模型解释。能控制工具时，优先返回字段清晰的字典，并让 schema 描述每个字段。

为什么不直接解析 Agent 的 content？普通文本不是稳定接口，可能包含解释、Markdown 或缺字段。结构化响应才适合交给业务代码。

结构化输出失败要不要自动重试？可对可恢复的字段错误重试；工具权限、数据库不可用等执行错误应保留真实原因并走业务降级，不能让模型编造一个成功结果。