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。
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预期输出
{"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;具体事件数量取决于任务实际执行了哪些动作。
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预期输出
READY
turn.completed真实事件流通常还会包含线程 ID、用量统计或工具执行事件,因此不要依赖固定行号。应该按 type 和具体 item.type 过滤,并把未知事件忽略或记录下来。
在流水线里判定成功
可靠的 CI 集成至少检查两层状态:第一层是 codex exec 的进程退出状态,用来发现认证、配置或运行级失败;第二层是 JSONL 中的语义事件,用来区分 turn.completed、turn.failed 和 error。只有进程成功并观察到预期完成事件,才进入后续业务步骤。
如果只需要稳定的最终对象,优先使用 --output-schema 和结果文件;如果还要做实时日志、工具调用审计或进度采集,再启用 --json。组合使用时要记住:Schema 约束最终响应,JSONL 描述执行过程,两者不应由同一段解析逻辑混为一种数据结构。