Agent Completion output_schema: fail a CI build when it is invalid

Bind a strict output_schema to an Agent Completion and your CI job can treat the receipt like a typed API response: pass only if status is completed, output is an object, and output_error is empty. A schema outside the strict subset is rejected before any run starts, so a bad schema fails the build in seconds instead of after a paid run. The contract is shared with Format and schedule runs.

What the docs say

The Agent Completions page lists output_schema and primary_output_key as optional fields and says the contract is the same as Action runs. The API-trigger page documents an output_schema shape of name, strict and schema, and the error output_schema_invalid with details.violations, each with a path, a rule and a message. Its example violation is required_completeness: every property must be listed in required, and optional values use a nullable type.

A schema that passes

The shape below follows the documented example: an object, additionalProperties: false, every property required, optional values nullable.

{
  "instruction": "Write a one-line caption for the attached product shot.",
  "generation_spend_cap_usd": 1,
  "output_schema": {
    "name": "ci/caption/v1",
    "strict": true,
    "schema": {
      "type": "object",
      "additionalProperties": false,
      "required": ["caption", "alt_text"],
      "properties": {
        "caption": {"type": "string"},
        "alt_text": {"type": ["string", "null"]}
      }
    }
  }
}

The CI gate

The Structured output page explains the failure modes. A run can finish its work and still fail to project into your schema; then output is null and output_error says why. Depending on the surface, that run may read as completed or failed, so a gate that reads only status is not enough. Check all three, and log output_error when it is set.

Keep schemas honest

Require only what the task makes. The docs warn that a schema demanding a field the recipe never produces fails on the projection path every time, silently until you read output_error. Keep your own identifiers on your side keyed by run id or idempotency key, because the projection step does not see your input.

Pin the schema name with a version, as in ci/caption/v1, and change the name when you change the shape. The receipt echoes the name verbatim, which makes it a handy label in test output.

Use a dedicated CI key from the dashboard, with agent_completions:write and agent_completions:read, as described on Authentication.