Structured outputs in the SDK

Get structured, validated JSON from agent workflows. The Agent SDK supports structured outputs through JSON Schemas, ensuring your agents return data in exactly the format you need.

Why use structured outputs

Structured outputs provide reliable, type-safe integration with your applications:

• Validated structure: Always receive valid JSON matching your schema
• Simplified integration: No parsing or validation code needed
• Type safety: Use with TypeScript or Python type hints for end-to-end safety
• Clean separation: Define output requirements separately from task instructions
• Tool autonomy: Agent chooses which tools to use while guaranteeing output format

How structured outputs work

Supported JSON Schema features

The Agent SDK supports the same JSON Schema features and limitations as API Structured Outputs.

Key supported features:

• All basic types: object, array, string, integer, number, boolean, null
• enum, const, required, additionalProperties (must be false)
• String formats: date-time, date, email, uri, uuid, etc.
• $ref, $def, and definitions

For complete details on supported features, limitations, and regex pattern support, see JSON Schema limitations in the API documentation.

Example: TODO tracking agent

Here's a complete example showing an agent that searches code for TODOs and extracts git blame information:

import { query } from '@anthropic-ai/claude-agent-sdk'

// Define structure for TODO extraction
const todoSchema = {
  type: 'object',
  properties: {
    todos: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          text: { type: 'string' },
          file: { type: 'string' },
          line: { type: 'number' },
          author: { type: 'string' },
          date: { type: 'string' }
        },
        required: ['text', 'file', 'line']
      }
    },
    total_count: { type: 'number' }
  },
  required: ['todos', 'total_count']
}

// Agent uses Grep to find TODOs, Bash to get git blame info
for await (const message of query({
  prompt: 'Find all TODO comments in src/ and identify who added them',
  options: {
    outputFormat: {
      type: 'json_schema',
      schema: todoSchema
    }
  }
})) {
  if (message.type === 'result' && message.structured_output) {
    const data = message.structured_output
    console.log(`Found ${data.total_count} TODOs`)
    data.todos.forEach(todo => {
      console.log(`${todo.file}:${todo.line} - ${todo.text}`)
      if (todo.author) {
        console.log(`  Added by ${todo.author} on ${todo.date}`)
      }
    })
  }
}

The agent autonomously uses the right tools (Grep, Bash) to gather information and returns validated data.

Error handling

If the agent cannot produce valid output matching your schema, you'll receive an error result:

for await (const msg of query({
  prompt: 'Analyze the data',
  options: {
    outputFormat: {
      type: 'json_schema',
      schema: mySchema
    }
  }
})) {
  if (msg.type === 'result') {
    if (msg.subtype === 'success' && msg.structured_output) {
      console.log(msg.structured_output)
    } else if (msg.subtype === 'error_max_structured_output_retries') {
      console.error('Could not produce valid output')
    }
  }
}

Related resources

• JSON Schema documentation
• API Structured Outputs - For single API calls
• Custom tools - Define tools for your agents
• TypeScript SDK reference - Full TypeScript API
• Python SDK reference - Full Python API