Use structured JSON output

Last updated: July 12, 2026

Use structured JSON output

Use structured JSON when an agent result needs to feed an API workflow, database, review queue, spreadsheet, or another system. The output type controls the artifact, while the default output schema controls the stable data contract for API calls.

Start in the Output step

Grep output type menu
The output type menu sets the visible artifact. The schema below it defines structured fields for API use.

Choose an artifact and define fields

Research report output with schema area
Structured JSON can sit alongside a human-readable artifact. Caller-supplied json_schema wins when the agent is called through the API.

Use a schema when field names, allowed values, and required evidence need to stay consistent across runs.

Default output schema area
Add fields for the data a downstream system needs, such as recommendation, confidence, rationale, and source URLs.

Schema design rules

  • Use stable field names that downstream systems can rely on.
  • Prefer enums for status, severity, recommendation, and confidence bands.
  • Separate the short answer from the supporting rationale.
  • Include source fields for evidence-heavy workflows.
  • Mark fields required only when every run can realistically provide them.
  • Keep deeply nested structures for genuinely nested data, not for decoration.

Example schema

{
  "recommendation": "approve | review | escalate",
  "confidence": "low | medium | high",
  "rationale": "Short explanation of the decision",
  "evidence": [
    {
      "source": "Source name",
      "url": "https://example.com",
      "finding": "Relevant evidence"
    }
  ],
  "missing_information": ["Any blocking gaps"]
}

Related articles