04 structured output | Knowledge Notes

它是什么

Subagent 可以设置 response_format，让子 Agent 最终结果按 schema 结构化。父 Agent 收到的是 JSON 序列化后的 ToolMessage 内容，不再是随意文本。它适合父 Agent 需要继续处理结果、传给下游工具或保存到结构化存储的场景。

常用程度

中高。只要父 Agent 后面还要程序化处理子 Agent 结果，就该优先考虑。

适合：

子 Agent 返回评分、置信度、sources、风险等级。
父 Agent 要把结果写数据库或传给另一个工具。
UI 需要固定字段展示。

不适合：

子 Agent 只需要返回一段总结。
schema 还没稳定，频繁改字段会让示例和下游都变烦。

父 Agent 收到什么

没有 response_format 时：

ToolMessage content = 子 Agent 最后一条文本

有 response_format 时：

ToolMessage content = JSON 字符串

所以父 Agent 或你的代码需要 json.loads(...) 后再处理字段。

最小代码

文件：deepagent_src/subagents_teach/04_structured_output.py

class LessonFinding(BaseModel):
    summary: str
    confidence: float
    sources: list[str]


structured_subagent = {
    "name": "structured-reporter",
    "description": "Use this subagent when the parent needs JSON findings.",
    "system_prompt": "Return structured data.",
    "response_format": LessonFinding,
}

运行

uv run python deepagent_src/subagents_teach/04_structured_output.py

预期输出末尾：

subagent structured output real agent ok

验证方式

脚本真实调用主 Agent，让它委派 structured-reporter；随后解析父 Agent 收到的 task 工具内容为 JSON，并断言字段符合 schema。

本章断言三个字段：

summary = structured-subagent-summary
confidence = 0.91
sources = ["subagent-docs"]

常见误区

structured output 约束的是 subagent 的最终返回结果，不是 subagent 内部每一步工具输出。

另一个坑：父 Agent 拿到的是 JSON 字符串，不是 Python 对象。你在应用代码里要自己解析。

相关资源

查看示例代码：deepagent_src/subagents_teach/04_structured_output.py

from __future__ import annotations

import json

from deepagents import create_deep_agent
from pydantic import BaseModel, Field

from _model import get_real_model
from deepagent_src.agent_output import invoke_and_pretty_print


class LessonFinding(BaseModel):
    """Structured result returned by a subagent."""

    summary: str = Field(description="Short summary")
    confidence: float = Field(description="Confidence from 0 to 1")
    sources: list[str] = Field(description="Source names")


structured_subagent = {
    "name": "structured-reporter",
    "description": "Use this subagent when the parent needs JSON findings.",
    "system_prompt": (
        "Return structured data with summary exactly 'structured-subagent-summary', "
        "confidence exactly 0.91, and sources exactly ['subagent-docs']."
    ),
    "tools": [],
    "response_format": LessonFinding,
}


def main() -> None:
    agent = create_deep_agent(
        model=get_real_model(),
        system_prompt=(
            "You are a coordinator. Delegate JSON finding requests to "
            "structured-reporter with the task tool. Do not ask clarification "
            "for this lesson."
        ),
        subagents=[structured_subagent],
    )
    result = invoke_and_pretty_print(
        agent,
        {
            "messages": [
                {
                    "role": "user",
                    "content": (
                        "必须调用 task 工具，subagent_type 必须是 structured-reporter。"
                        "任务描述：返回本课固定结构化 findings。"
                    ),
                }
            ]
        },
    )

    task_outputs = [
        getattr(message, "content", "")
        for message in result["messages"]
        if getattr(message, "name", "") == "task"
    ]
    parsed = json.loads(task_outputs[-1])

    assert parsed["summary"] == "structured-subagent-summary"
    assert parsed["confidence"] == 0.91
    assert parsed["sources"] == ["subagent-docs"]
    print("subagent structured output real agent ok")


if __name__ == "__main__":
    main()