AI Agent / 系统课时

处理结构化输出

处理结构化输出

当 Codex 的结果要进入脚本、CI 或数据处理链路时,仅靠自然语言文本很难稳定解析。本节会把“最终业务结果的固定字段”和“运行过程的 JSONL 事件流”分开处理,并给出可直接用 jq 验证的接入方式。

学习目标

  • 使用 --output-schema 约束最终响应的数据结构
  • 使用 --json 消费 Codex 的 JSON Lines 事件流
  • 在流水线中同时判断进程状态、完成事件和最终业务数据

区分结果结构和事件流

codex exec 是 Codex CLI 的非交互执行入口。--output-schema 约束的是最终代理响应的形状,适合让下游拿到固定字段;--json 改变的是运行过程的输出协议,使 stdout 成为一行一个 JSON 对象的 JSONL 事件流。两者解决的问题不同,也可以在同一次执行中组合。

需求 选项 适合的消费者
固定最终字段 --output-schema 配合 -o 部署脚本、报告生成器、CI 后续步骤
观察完整执行过程 --json 日志采集器、事件处理器、实时流水线

JSONL 不是一个大型 JSON 数组。消费者应逐行解析,并允许出现自己暂时不关心的事件类型,避免 CLI 新增事件后导致整个流水线崩溃。

用 JSON Schema 固定最终结果

下面先定义一个只允许 status 和 summary 两个字段的 Schema,再让 Codex 把最终响应写入 result.json。示例假设已经安装并登录 Codex CLI,当前目录是可运行的 Git 项目,并且系统已安装 jq。

bash
cat >schema.json <<'JSON'
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": ["ok"]
    },
    "summary": {
      "type": "string"
    }
  },
  "required": ["status", "summary"],
  "additionalProperties": false
}
JSON

codex exec --output-schema ./schema.json -o ./result.json 'Return status "ok" and summary exactly "pipeline-ready".' >/dev/null 2>codex.err
jq -c . ./result.json

预期输出

json
{"status":"ok","summary":"pipeline-ready"}

这里的 Schema 约束最终响应,而 result.json 是下游真正应该读取的业务文件。若 Schema 文件不是合法 JSON,或运行阶段发生错误,脚本应停止后续步骤并检查退出状态与 codex.err。

消费 JSONL 事件

开启 --json 后,stdout 不再只是最终消息,而是运行期间连续产生的事件。常见事件包括 thread.started、turn.started、item.*、turn.completed、turn.failed 和 error;具体事件数量取决于任务实际执行了哪些动作。

bash
codex exec --json 'Output exactly: READY' >events.jsonl 2>codex.err

jq -r 'select(.type == "item.completed" and .item.type == "agent_message") | .item.text' events.jsonl
jq -r 'select(.type == "turn.completed") | .type' events.jsonl

预期输出

text
READY
turn.completed

真实事件流通常还会包含线程 ID、用量统计或工具执行事件,因此不要依赖固定行号。应该按 type 和具体 item.type 过滤,并把未知事件忽略或记录下来。

在流水线里判定成功

可靠的 CI 集成至少检查两层状态:第一层是 codex exec 的进程退出状态,用来发现认证、配置或运行级失败;第二层是 JSONL 中的语义事件,用来区分 turn.completed、turn.failed 和 error。只有进程成功并观察到预期完成事件,才进入后续业务步骤。

如果只需要稳定的最终对象,优先使用 --output-schema 和结果文件;如果还要做实时日志、工具调用审计或进度采集,再启用 --json。组合使用时要记住:Schema 约束最终响应,JSONL 描述执行过程,两者不应由同一段解析逻辑混为一种数据结构。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

处理结构化输出

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通