Skip to main content
When a script or another system reads an agent’s answer, pass output_schema with the question. The agent does its work as usual, then returns its final result as JSON that matches the schema.

Where it works

Schema rules

The schema is checked before the agent starts, so a schema that can’t be used costs nothing.
  • Every object sets "additionalProperties": false.
  • Every property is listed in required. For a value that may be missing, make the field required and allow null in its type.
  • References to other documents ($ref to a URL) aren’t supported.

Reading the result

The result is in output. With a schema it is the JSON value; without one it is the agent’s text answer. Status, run ID, model and usage sit beside it. An async request returns at once with an invocation_id. Read the finished run from GET /v1/runs/{run_id}, which also returns output, or let the CLI wait for you. The older answer field and the run’s text output still work while clients move to output.

When the result doesn’t match

If the agent’s final result doesn’t match the schema, the run fails with error_type: "output_schema_mismatch" and an error saying which part didn’t match. Nothing is retried automatically, and you are charged for the work the agent did. A run waiting for an approval or for your answer to a question is paused, not finished, and has no output yet.