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

定义 schema 并创建智能体

先完成安装与模型配置,选择支持结构化输出的模型。下面使用 Literal 限定分类和优先级;仅在字段描述中列出取值不能形成同等的校验约束
ticket.py

解析返回结果

运行 python ticket.py。成功时输出类似以下 JSON,摘要措辞和分类判断可能随模型变化:
Runner.run 返回文本,不会直接返回 Ticket 实例。Ticket.model_validate_json(raw) 同时完成 JSON 解析和字段校验。示例中的校验失败处理不涵盖模型请求异常;生产应用应分别处理请求失败和结果不合格,也应检查业务规则,例如工单是否包含足够的信息

使用方舟原生结构化输出

模型和端点需同时支持火山方舟 Responses API 与 JSON Schema。将上例中的 agent 定义替换为:
VeADK 会将 schema 转换为 Responses API 的 json_schema 格式并设置 strict: true。服务是否接受该 schema、支持哪些约束,仍取决于所用模型和服务。不要将这种配置理解为请求永远成功或内容始终符合业务事实 Responses 缓存与结构化输出存在兼容限制,VeADK 会在相关请求上移除冲突的缓存设置。显式设置 enable_responses_cache=False 可以让该选择更清楚,其他配置见Responses API

工具与运行时限制

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