结构化输出

结构化输出让 Agent 在完成任务后返回符合指定 JSON Schema 的验证数据，而非自由文本。Agent 可以自由使用任意工具完成任务，最终输出仍然是可直接用于程序逻辑的结构化数据。

核心机制

工作原理：传入 JSON Schema → Agent 完成任务（可使用任意工具）→ SDK 验证输出是否符合 Schema → 不符合则自动重试 → 超过重试次数返回错误。

配置方式：通过 output_format（Python）或 outputFormat（TypeScript）选项传入 Schema。

结果位置：ResultMessage.structured_output（仅 subtype == "success" 时有值）。

错误处理：验证失败超过重试次数时，ResultMessage.subtype == "error_max_structured_output_retries"。

关键细节

基础用法（JSON Schema）：

schema = {
    "type": "object",
    "properties": {
        "company_name": {"type": "string"},
        "founded_year": {"type": "number"},
    },
    "required": ["company_name"],
}
 
async for message in query(
    prompt="Research Anthropic and provide key company information",
    options=ClaudeAgentOptions(output_format={"type": "json_schema", "schema": schema}),
):
    if isinstance(message, ResultMessage) and message.structured_output:
        print(message.structured_output)

类型安全（Pydantic）：

from pydantic import BaseModel
 
class FeaturePlan(BaseModel):
    feature_name: str
    steps: list[dict]
    risks: list[str]
 
async for message in query(
    prompt="Plan how to add dark mode...",
    options=ClaudeAgentOptions(
        output_format={"type": "json_schema", "schema": FeaturePlan.model_json_schema()}
    ),
):
    if isinstance(message, ResultMessage) and message.structured_output:
        plan = FeaturePlan.model_validate(message.structured_output)

TypeScript 用 Zod：z.toJSONSchema(MySchema) 生成 JSON Schema，MySchema.safeParse(result) 验证。

结构化输出与流式：JSON 结果只在最终 ResultMessage 中出现，不以流式增量形式传输。

与其他概念的关联

• agent-loop - ResultMessage 中的 structured_output 字段
• streaming-output - 结构化输出与流式的兼容性限制
• custom-tools - 工具返回 structuredContent（Python 不支持）

实践要点

• Schema 越简单越好，深层嵌套和大量必填字段会增加验证失败概率
• 任务可能没有所有字段的信息时，将对应字段设为可选
• prompt 要清晰，模糊的任务描述会导致 Agent 不知道该输出什么
• 适用场景：数据提取、报告生成、API 响应格式化、将 Agent 输出集成到下游系统