output_schema 后,运行时会向模型提供结构约束;应用仍应校验返回内容,处理空响应、格式错误和不满足业务规则的结果
定义 schema 并创建智能体
先完成安装与模型配置,选择支持结构化输出的模型。下面使用Literal 限定分类和优先级;仅在字段描述中列出取值不能形成同等的校验约束
ticket.py
解析返回结果
运行python ticket.py。成功时输出类似以下 JSON,摘要措辞和分类判断可能随模型变化:
Runner.run 返回文本,不会直接返回 Ticket 实例。Ticket.model_validate_json(raw) 同时完成 JSON 解析和字段校验。示例中的校验失败处理不涵盖模型请求异常;生产应用应分别处理请求失败和结果不合格,也应检查业务规则,例如工单是否包含足够的信息
使用方舟原生结构化输出
模型和端点需同时支持火山方舟 Responses API 与 JSON Schema。将上例中的agent 定义替换为:
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 版本一起确认 - 需要稳定地组合检索、工具和抽取时,可先完成工具任务,再由单独的结构化输出智能体生成最终记录