Saídas estruturadas no SDK

Obtenha JSON estruturado e validado de fluxos de trabalho de agentes. O Agent SDK suporta saídas estruturadas através de JSON Schemas, garantindo que seus agentes retornem dados exatamente no formato que você precisa.

Por que usar saídas estruturadas

Saídas estruturadas fornecem integração confiável e type-safe com suas aplicações:

• Estrutura validada: Sempre receba JSON válido correspondendo ao seu schema
• Integração simplificada: Nenhum código de análise ou validação necessário
• Segurança de tipo: Use com dicas de tipo TypeScript ou Python para segurança end-to-end
• Separação limpa: Defina requisitos de saída separadamente das instruções de tarefa
• Autonomia de ferramentas: O agente escolhe quais ferramentas usar enquanto garante o formato de saída

Como funcionam as saídas estruturadas

Recursos de JSON Schema suportados

O Agent SDK suporta os mesmos recursos e limitações de JSON Schema que Saídas Estruturadas de API.

Recursos principais suportados:

• Todos os tipos básicos: object, array, string, integer, number, boolean, null
• enum, const, required, additionalProperties (deve ser false)
• Formatos de string: date-time, date, email, uri, uuid, etc.
• $ref, $def, e definitions

Para detalhes completos sobre recursos suportados, limitações e suporte a padrões regex, consulte Limitações de JSON Schema na documentação da API.

Exemplo: agente de rastreamento de TODO

Aqui está um exemplo completo mostrando um agente que pesquisa código para TODOs e extrai informações de git blame:

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

// Defina estrutura para extração de TODO
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']
}

// O agente usa Grep para encontrar TODOs, Bash para obter informações de git blame
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}`)
      }
    })
  }
}

O agente usa autonomamente as ferramentas certas (Grep, Bash) para reunir informações e retorna dados validados.

Tratamento de erros

Se o agente não conseguir produzir saída válida correspondendo ao seu schema, você receberá um resultado de erro:

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')
    }
  }
}

Recursos relacionados

• Documentação de JSON Schema
• Saídas Estruturadas de API - Para chamadas de API única
• Ferramentas personalizadas - Defina ferramentas para seus agentes
• Referência do SDK TypeScript - API TypeScript completa
• Referência do SDK Python - API Python completa