结构化输出

结构化输出允许 agents 以特定的、可预测的格式返回数据。您将获得类型化的结构化数据，而不是解析自然语言响应。

本页涵盖了使用 createAgent 的 agents 的结构化输出。要直接在模型上使用结构化输出（在 agents 之外），请参阅模型 - 结构化输出。

LangChain 的预构建 ReAct agent createAgent 自动处理结构化输出。用户设置他们期望的结构化输出模式，当模型生成结构化数据时，它会被捕获、验证并在 agent 状态的 structuredResponse 键中返回。

type ResponseFormat = (
    | ZodSchema<StructuredResponseT> // a Zod schema
    | Record<string, unknown> // a JSON Schema
)

const agent = createAgent({
    // ...
    responseFormat: ResponseFormat | ResponseFormat[]
})

响应格式

控制 agent 如何返回结构化数据。您可以提供 Zod 对象或 JSON schema。默认情况下，agent 使用工具调用策略，其中输出由附加的工具调用创建。某些模型支持原生结构化输出，在这种情况下，agent 将改为使用该策略。您可以通过将 ResponseFormat 包装在 toolStrategy 或 providerStrategy 函数调用中来控制行为：

import { toolStrategy, providerStrategy } from "langchain";

const agent = createAgent({
    // use a provider strategy if supported by the model
    responseFormat: providerStrategy(z.object({ ... }))
    // or enforce a tool strategy
    responseFormat: toolStrategy(z.object({ ... }))
})

结构化响应在 agent 最终状态的 structuredResponse 键中返回。

如果使用 langchain>=1.1，对原生结构化输出功能的支持将从模型的配置文件数据中动态读取。如果数据不可用，请使用其他条件或手动指定：

const customProfile: ModelProfile = {
    structuredOutput: true,
    // ...
}
const model = await initChatModel("...", { profile: customProfile });

如果指定了工具，模型必须支持同时使用工具和结构化输出。

提供者策略 (Provider strategy)

一些模型提供者通过其 API 原生支持结构化输出（例如 OpenAI, xAI (Grok), Gemini, Anthropic (Claude)）。当可用时，这是最可靠的方法。要使用此策略，请配置 ProviderStrategy：

function providerStrategy<StructuredResponseT>(
    schema: ZodSchema<StructuredResponseT> | JsonSchemaFormat
): ProviderStrategy<StructuredResponseT>

schema

required

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

Zod Schema: 一个 zod 模式
JSON Schema: 一个 JSON 模式对象

当您将模式类型直接传递给 createAgent.responseFormat 并且模型支持原生结构化输出时，LangChain 会自动使用 ProviderStrategy：

import * as z from "zod";
import { createAgent, providerStrategy } from "langchain";

const ContactInfo = z.object({
    name: z.string().describe("The name of the person"),
    email: z.string().describe("The email address of the person"),
    phone: z.string().describe("The phone number of the person"),
});

const agent = createAgent({
    model: "gpt-5",
    tools: [],
    responseFormat: providerStrategy(ContactInfo)
});

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

console.log(result.structuredResponse);
// { name: "John Doe", email: "john@example.com", phone: "(555) 123-4567" }

提供者原生的结构化输出提供了高可靠性和严格的验证，因为模型提供者强制执行模式。尽量使用它。

如果提供者原生支持您选择的模型的结构化输出，则编写 responseFormat: contactInfoSchema 与 responseFormat: providerStrategy(contactInfoSchema) 在功能上是等效的。在任何一种情况下，如果不支持结构化输出，agent 将回退到工具调用策略。

工具调用策略 (Tool calling strategy)

对于不支持原生结构化输出的模型，LangChain 使用工具调用来实现相同的结果。这适用于所有支持工具调用的模型（大多数现代模型）。要使用此策略，请配置 ToolStrategy：

function toolStrategy<StructuredResponseT>(
    responseFormat:
        | JsonSchemaFormat
        | ZodSchema<StructuredResponseT>
        | (ZodSchema<StructuredResponseT> | JsonSchemaFormat)[]
    options?: ToolStrategyOptions
): ToolStrategy<StructuredResponseT>

schema

required

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

Zod Schema: 一个 zod 模式
JSON Schema: 一个 JSON 模式对象

options.toolMessageContent

生成结构化输出时返回的工具消息的自定义内容。如果未提供，则默认为显示结构化响应数据的消息。

options.handleError

Options 参数，包含一个可选的 handleError 参数，用于自定义错误处理策略。

true: 使用默认错误模板捕获所有错误（默认）
False: 不重试，让异常传播
(error: ToolStrategyError) => string | Promise<string>: 使用提供的消息重试或抛出错误

import * as z from "zod";
import { createAgent, toolStrategy } from "langchain";

const ProductReview = z.object({
    rating: z.number().min(1).max(5).optional(),
    sentiment: z.enum(["positive", "negative"]),
    keyPoints: z.array(z.string()).describe("The key points of the review. Lowercase, 1-3 words each."),
});

const agent = createAgent({
    model: "gpt-5",
    tools: [],
    responseFormat: toolStrategy(ProductReview)
})

const result = await agent.invoke({
    "messages": [{"role": "user", "content": "Analyze this review: 'Great product: 5 out of 5 stars. Fast shipping, but expensive'"}]
})

console.log(result.structuredResponse);
// { "rating": 5, "sentiment": "positive", "keyPoints": ["fast shipping", "expensive"] }

自定义工具消息内容

toolMessageContent 参数允许您自定义在生成结构化输出时出现在对话历史记录中的消息：

import * as z from "zod";
import { createAgent, toolStrategy } from "langchain";

const MeetingAction = z.object({
    task: z.string().describe("The specific task to be completed"),
    assignee: z.string().describe("Person responsible for the task"),
    priority: z.enum(["low", "medium", "high"]).describe("Priority level"),
});

const agent = createAgent({
    model: "gpt-5",
    tools: [],
    responseFormat: toolStrategy(MeetingAction, {
        toolMessageContent: "Action item captured and added to meeting notes!"
    })
});

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

console.log(result);
/**
 * {
 *   messages: [
 *     { role: "user", content: "From our meeting: Sarah needs to update the project timeline as soon as possible" },
 *     { role: "assistant", content: "Action item captured and added to meeting notes!", tool_calls: [ { name: "MeetingAction", args: { task: "update the project timeline", assignee: "Sarah", priority: "high" }, id: "call_456" } ] },
 *     { role: "tool", content: "Action item captured and added to meeting notes!", tool_call_id: "call_456", name: "MeetingAction" }
 *   ],
 *   structuredResponse: { task: "update the project timeline", assignee: "Sarah", priority: "high" }
 * }
 */

如果没有 toolMessageContent，我们会看到：

# console.log(result);
/**
 * {
 *   messages: [
 *     ...
 *     { role: "tool", content: "Returning structured response: {'task': 'update the project timeline', 'assignee': 'Sarah', 'priority': 'high'}", tool_call_id: "call_456", name: "MeetingAction" }
 *   ],
 *   structuredResponse: { task: "update the project timeline", assignee: "Sarah", priority: "high" }
 * }
 */

错误处理

通过工具调用生成结构化输出时，模型可能会犯错。LangChain 提供了智能重试机制来自动处理这些错误。

多个结构化输出错误

当模型错误地调用多个结构化输出工具时，agent 在 ToolMessage 中提供错误反馈并提示模型重试：

import * as z from "zod";
import { createAgent, toolStrategy } from "langchain";

const ContactInfo = z.object({
    name: z.string().describe("Person's name"),
    email: z.string().describe("Email address"),
});

const EventDetails = z.object({
    event_name: z.string().describe("Name of the event"),
    date: z.string().describe("Event date"),
});

const agent = createAgent({
    model: "gpt-5",
    tools: [],
    responseFormat: toolStrategy([ContactInfo, EventDetails]),
});

const result = await agent.invoke({
    messages: [
        {
        role: "user",
        content:
            "Extract info: John Doe (john@email.com) is organizing Tech Conference on March 15th",
        },
    ],
});

console.log(result);

/**
 * {
 *   messages: [
 *     { role: "user", content: "Extract info: John Doe (john@email.com) is organizing Tech Conference on March 15th" },
 *     { role: "assistant", content: "", tool_calls: [ { name: "ContactInfo", args: { name: "John Doe", email: "john@email.com" }, id: "call_1" }, { name: "EventDetails", args: { event_name: "Tech Conference", date: "March 15th" }, id: "call_2" } ] },
 *     { role: "tool", content: "Error: Model incorrectly returned multiple structured responses (ContactInfo, EventDetails) when only one is expected.\n Please fix your mistakes.", tool_call_id: "call_1", name: "ContactInfo" },
 *     { role: "tool", content: "Error: Model incorrectly returned multiple structured responses (ContactInfo, EventDetails) when only one is expected.\n Please fix your mistakes.", tool_call_id: "call_2", name: "EventDetails" },
 *     { role: "assistant", content: "", tool_calls: [ { name: "ContactInfo", args: { name: "John Doe", email: "john@email.com" }, id: "call_3" } ] },
 *     { role: "tool", content: "Returning structured response: {'name': 'John Doe', 'email': 'john@email.com'}", tool_call_id: "call_3", name: "ContactInfo" }
 *   ],
 *   structuredResponse: { name: "John Doe", email: "john@email.com" }
 * }
 */

模式验证错误

当结构化输出与预期模式不匹配时，agent 会提供具体的错误反馈：

import * as z from "zod";
import { createAgent, toolStrategy } from "langchain";

const ProductRating = z.object({
    rating: z.number().min(1).max(5).describe("Rating from 1-5"),
    comment: z.string().describe("Review comment"),
});

const agent = createAgent({
    model: "gpt-5",
    tools: [],
    responseFormat: toolStrategy(ProductRating),
});

const result = await agent.invoke({
    messages: [
        {
        role: "user",
        content: "Parse this: Amazing product, 10/10!",
        },
    ],
});

console.log(result);

/**
 * {
 *   messages: [
 *     { role: "user", content: "Parse this: Amazing product, 10/10!" },
 *     { role: "assistant", content: "", tool_calls: [ { name: "ProductRating", args: { rating: 10, comment: "Amazing product" }, id: "call_1" } ] },
 *     { role: "tool", content: "Error: Failed to parse structured output for tool 'ProductRating': 1 validation error for ProductRating\nrating\n  Input should be less than or equal to 5 [type=less_than_equal, input_value=10, input_type=int].\n Please fix your mistakes.", tool_call_id: "call_1", name: "ProductRating" },
 *     { role: "assistant", content: "", tool_calls: [ { name: "ProductRating", args: { rating: 5, comment: "Amazing product" }, id: "call_2" } ] },
 *     { role: "tool", content: "Returning structured response: {'rating': 5, 'comment': 'Amazing product'}", tool_call_id: "call_2", name: "ProductRating" }
 *   ],
 *   structuredResponse: { rating: 5, comment: "Amazing product" }
 * }
 */

错误处理策略

您可以使用 handleErrors 参数自定义错误的处理方式： 自定义错误消息：

const responseFormat = toolStrategy(ProductRating, {
    handleError: "Please provide a valid rating between 1-5 and include a comment."
)

// Error message becomes:
// { role: "tool", content: "Please provide a valid rating between 1-5 and include a comment." }

仅处理特定异常：

import { ToolInputParsingException } from "@langchain/core/tools";

const responseFormat = toolStrategy(ProductRating, {
    handleError: (error: ToolStrategyError) => {
        if (error instanceof ToolInputParsingException) {
        return "Please provide a valid rating between 1-5 and include a comment.";
        }
        return error.message;
    }
)

// Only validation errors get retried with default message:
// { role: "tool", content: "Error: Failed to parse structured output for tool 'ProductRating': ...\n Please fix your mistakes." }

处理多种异常类型：

const responseFormat = toolStrategy(ProductRating, {
    handleError: (error: ToolStrategyError) => {
        if (error instanceof ToolInputParsingException) {
        return "Please provide a valid rating between 1-5 and include a comment.";
        }
        if (error instanceof CustomUserError) {
        return "This is a custom user error.";
        }
        return error.message;
    }
)

无错误处理：

const responseFormat = toolStrategy(ProductRating, {
    handleError: false  // All errors raised
})

在 GitHub 上编辑此页面或提交 issue。

将这些文档连接到 Claude、VSCode 等，通过 MCP 获得实时解答。

Get started

Core components

Middleware

Advanced usage

Agent development

Deploy with LangSmith

响应格式

提供者策略 (Provider strategy)

工具调用策略 (Tool calling strategy)

自定义工具消息内容

错误处理

多个结构化输出错误

模式验证错误

错误处理策略

Get started

Core components

Middleware

Advanced usage

Agent development

Deploy with LangSmith

​响应格式

​提供者策略 (Provider strategy)

​工具调用策略 (Tool calling strategy)

​自定义工具消息内容

​错误处理

​多个结构化输出错误

​模式验证错误

​错误处理策略

响应格式

提供者策略 (Provider strategy)

工具调用策略 (Tool calling strategy)

自定义工具消息内容

错误处理

多个结构化输出错误

模式验证错误

错误处理策略