> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 结构化输出

结构化输出让智能体按预先定义的字段返回结果，适合信息抽取、分类和后续程序处理。将 Pydantic 模型传给 `output_schema` 后，运行时会向模型提供结构约束；应用仍应校验返回内容，处理空响应、格式错误和不满足业务规则的结果

## 定义 schema 并创建智能体

先完成[安装与模型配置](/productions/veadk/preview/zh/get-started/quickstart)，选择支持结构化输出的模型。下面使用 `Literal` 限定分类和优先级；仅在字段描述中列出取值不能形成同等的校验约束

```python ticket.py lines theme={null}
import asyncio
from typing import Literal
from pydantic import BaseModel, Field, ValidationError
from veadk import Agent, Runner

class Ticket(BaseModel):
    summary: str = Field(description="A one-sentence summary of the issue")
    category: Literal["billing", "bug", "feature_request", "other"]
    priority: Literal["low", "medium", "high"]

agent = Agent(
    name="ticket_extractor",
    instruction="Extract one support ticket from the user's message.",
    output_schema=Ticket,
)

async def main():
    raw = await Runner(agent=agent, app_name="structured_output").run(
        messages="The billing page crashes every time I open it. Please fix it urgently.",
        session_id="ticket-demo",
    )
    try:
        ticket = Ticket.model_validate_json(raw)
    except ValidationError:
        print("The response is not a valid ticket. Do not save it as a completed record.")
        return
    print(ticket.model_dump_json(indent=2))

if __name__ == "__main__":
    asyncio.run(main())
```

## 解析返回结果

运行 `python ticket.py`。成功时输出类似以下 JSON，摘要措辞和分类判断可能随模型变化：

```json lines theme={null}
{
  "summary": "The billing page crashes whenever it is opened",
  "category": "bug",
  "priority": "high"
}
```

`Runner.run` 返回文本，不会直接返回 `Ticket` 实例。`Ticket.model_validate_json(raw)` 同时完成 JSON 解析和字段校验。示例中的校验失败处理不涵盖模型请求异常；生产应用应分别处理请求失败和结果不合格，也应检查业务规则，例如工单是否包含足够的信息

| 参数 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- |
| `output_schema` | Pydantic 模型类 | `None` | 最终回复的结构；传入 `Ticket`，而非 `Ticket()` |
| `output_key` | `str \| None` | `None` | 将最终结果保存到会话状态；ADK 在配置 schema 时会解析并校验后保存 |
| `enable_responses` | `bool` | `False` | 使用火山方舟 Responses API |
| `enable_responses_cache` | `bool` | `True` | Responses 缓存开关；结构化输出示例中显式关闭 |

## 使用方舟原生结构化输出

模型和端点需同时支持火山方舟 Responses API 与 JSON Schema。将上例中的 `agent` 定义替换为：

```python lines theme={null}
agent = Agent(
    name="ticket_extractor",
    instruction="Extract one support ticket from the user's message.",
    output_schema=Ticket,
    enable_responses=True,
    enable_responses_cache=False,
)
```

VeADK 会将 schema 转换为 Responses API 的 `json_schema` 格式并设置 `strict: true`。服务是否接受该 schema、支持哪些约束，仍取决于所用模型和服务。不要将这种配置理解为请求永远成功或内容始终符合业务事实

Responses 缓存与结构化输出存在兼容限制，VeADK 会在相关请求上移除冲突的缓存设置。显式设置 `enable_responses_cache=False` 可以让该选择更清楚，其他配置见[Responses API](/productions/veadk/preview/zh/components/agent/model#responses-api)

## 工具与运行时限制

* 使用默认的 `adk` 运行时；`codex` 和 `piagent` 运行时不支持 `output_schema`，配置时会报错
* Google ADK 2.2 支持同时配置 `output_schema` 和工具，结构约束用于最终回答；工具调用和任务转交的实际兼容性仍需与所用模型、接口及 ADK 版本一起确认
* 需要稳定地组合检索、工具和抽取时，可先完成工具任务，再由单独的结构化输出智能体生成最终记录