结构化输出与 SDK 版本

使用 JSON Schema 描述结果，并区分官方示例和 v2 类型字段。

This page has not been translated into English yet. The original Chinese version is shown below.

结构化输出通过 StructuredOutput 工具让模型返回符合 JSON Schema 的对象。普通 text 是默认输出类型；需要验证 JSON 形状时使用 json_schema。

描述期望的数据

请求中的 format 对象可以写成：

{
  "type": "json_schema",
  "schema": {
    "type": "object",
    "properties": {
      "summary": {
        "type": "string",
        "description": "A short summary of the repository"
      },
      "languages": {
        "type": "array",
        "items": { "type": "string" }
      }
    },
    "required": ["summary", "languages"]
  },
  "retryCount": 2
}

type 与 schema 必填，retryCount 可选，官方 SDK 页给出的验证重试默认值是 2。通过字段 description 说明含义，用 required 明确必填，避免为一个小任务设计过深的嵌套结构。

先确认 SDK 入口

截至核验日期，官方 SDK 页同时出现 body.format 和方法表里的 body.outputFormat；示例还以 structured_output 读取结果。对照同一仓库提交的生成类型：

位置	已核实的类型形状
默认 `@opencode-ai/sdk` 的 SessionPromptData	没有 format / outputFormat 字段
`@opencode-ai/sdk/v2` 的 SessionPromptData	请求体字段是 `format?: OutputFormat`，路径字段为 `sessionID`
v2 的 AssistantMessage	结果字段是 `structured?: unknown`
v2 的 StructuredOutputError	`name` 为 `StructuredOutputError`，详情放在 `data.message` 与 `data.retries`

因此不能原样拼接文档里的默认 import、path.id、format 与 structured_output。上面的 JSON 只展示 format 的内容；实际调用形状应由已安装 SDK 入口和类型定义确定，不能通过类型断言绕过不匹配。

处理失败

官方说明所有验证重试失败后，消息携带 StructuredOutputError。这与 HTTP 客户端错误不同：即使请求返回，仍需检查助手消息中的 error，再读取结构化值。

v2 类型将结果定义为 unknown；业务程序还应按自己的数据类型验证或收窄结果。客户端的 throwOnError 控制 API 错误处理，不应把它理解为自动处理所有模型输出验证失败。

本页记录的是所核验官方提交的差异，不承诺后续发布保持相同字段；更新 SDK 后应重新检查生成类型和服务端 OpenAPI。