Obter saída estruturada de agentes

Saídas estruturadas permitem que você defina a forma exata dos dados que deseja receber de um agente. O agente pode usar qualquer ferramenta que precisar para completar a tarefa, e você ainda obtém JSON validado correspondente ao seu schema no final. Defina um JSON Schema para a estrutura que você precisa, e o SDK garante que a saída corresponda a ele.

Para segurança de tipo completa, use Zod (TypeScript) ou Pydantic (Python) para definir seu schema e obter objetos fortemente tipados de volta.

Por que saídas estruturadas?

Agentes retornam texto livre por padrão, o que funciona para chat, mas não quando você precisa usar a saída programaticamente. Saídas estruturadas fornecem dados tipados que você pode passar diretamente para sua lógica de aplicação, banco de dados ou componentes de UI.

Considere um aplicativo de receitas onde um agente pesquisa a web e traz receitas. Sem saídas estruturadas, você obtém texto livre que precisaria analisar você mesmo. Com saídas estruturadas, você define a forma que deseja e obtém dados tipados que pode usar diretamente em seu aplicativo.

Início rápido

Para usar saídas estruturadas, defina um JSON Schema descrevendo a forma dos dados que você deseja, depois passe-o para query() via a opção outputFormat (TypeScript) ou output_format (Python). Quando o agente terminar, a mensagem de resultado inclui um campo structured_output com dados validados correspondendo ao seu schema.

O exemplo abaixo pede ao agente para pesquisar Anthropic e retornar o nome da empresa, ano de fundação e sede como saída estruturada.

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

// Define a forma dos dados que você deseja receber
const schema = {
  type: 'object',
  properties: {
    company_name: { type: 'string' },
    founded_year: { type: 'number' },
    headquarters: { type: 'string' }
  },
  required: ['company_name']
}

for await (const message of query({
  prompt: 'Research Anthropic and provide key company information',
  options: {
    outputFormat: {
      type: 'json_schema',
      schema: schema
    }
  }
})) {
  // A mensagem de resultado contém structured_output com dados validados
  if (message.type === 'result' && message.structured_output) {
    console.log(message.structured_output)
    // { company_name: "Anthropic", founded_year: 2021, headquarters: "San Francisco, CA" }
  }
}

Schemas type-safe com Zod e Pydantic

Em vez de escrever JSON Schema manualmente, você pode usar Zod (TypeScript) ou Pydantic (Python) para definir seu schema. Essas bibliotecas geram o JSON Schema para você e permitem que você analise a resposta em um objeto totalmente tipado que você pode usar em todo seu codebase com autocomplete e verificação de tipo.

O exemplo abaixo define um schema para um plano de implementação de recurso com um resumo, lista de etapas (cada uma com nível de complexidade) e riscos potenciais. O agente planeja o recurso e retorna um objeto FeaturePlan tipado. Você pode então acessar propriedades como plan.summary e iterar sobre plan.steps com segurança de tipo completa.

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

// Define schema com Zod
const FeaturePlan = z.object({
  feature_name: z.string(),
  summary: z.string(),
  steps: z.array(z.object({
    step_number: z.number(),
    description: z.string(),
    estimated_complexity: z.enum(['low', 'medium', 'high'])
  })),
  risks: z.array(z.string())
})

type FeaturePlan = z.infer<typeof FeaturePlan>

// Converta para JSON Schema
const schema = z.toJSONSchema(FeaturePlan)

// Use em query
for await (const message of query({
  prompt: 'Plan how to add dark mode support to a React app. Break it into implementation steps.',
  options: {
    outputFormat: {
      type: 'json_schema',
      schema: schema
    }
  }
})) {
  if (message.type === 'result' && message.structured_output) {
    // Valide e obtenha resultado totalmente tipado
    const parsed = FeaturePlan.safeParse(message.structured_output)
    if (parsed.success) {
      const plan: FeaturePlan = parsed.data
      console.log(`Feature: ${plan.feature_name}`)
      console.log(`Summary: ${plan.summary}`)
      plan.steps.forEach(step => {
        console.log(`${step.step_number}. [${step.estimated_complexity}] ${step.description}`)
      })
    }
  }
}

Benefícios:

• Inferência de tipo completa (TypeScript) e dicas de tipo (Python)
• Validação em tempo de execução com safeParse() ou model_validate()
• Mensagens de erro melhores
• Schemas compostos e reutilizáveis

Configuração do formato de saída

A opção outputFormat (TypeScript) ou output_format (Python) aceita um objeto com:

• type: Defina como "json_schema" para saídas estruturadas
• schema: Um objeto JSON Schema definindo sua estrutura de saída. Você pode gerar isso a partir de um schema Zod com z.toJSONSchema() ou um modelo Pydantic com .model_json_schema()

O SDK suporta recursos padrão de JSON Schema, incluindo todos os tipos básicos (object, array, string, number, boolean, null), enum, const, required, objetos aninhados e definições $ref. Para a lista completa de recursos suportados e limitações, veja Limitações de JSON Schema.

Exemplo: agente de rastreamento de TODO

Este exemplo demonstra como saídas estruturadas funcionam com uso de ferramentas em múltiplas etapas. O agente precisa encontrar comentários TODO no codebase, depois procurar informações de git blame para cada um. Ele decide autonomamente quais ferramentas usar (Grep para pesquisar, Bash para executar comandos git) e combina os resultados em uma única resposta estruturada.

O schema inclui campos opcionais (author e date) já que informações de git blame podem não estar disponíveis para todos os arquivos. O agente preenche o que consegue encontrar e omite o resto.

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

// Define 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']
}

// 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 this codebase 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}`)
      }
    })
  }
}

Tratamento de erros

A geração de saída estruturada pode falhar quando o agente não consegue produzir JSON válido correspondendo ao seu schema. Isso normalmente acontece quando o schema é muito complexo para a tarefa, a tarefa em si é ambígua, ou o agente atinge seu limite de tentativas ao tentar corrigir erros de validação.

Quando um erro ocorre, a mensagem de resultado tem um subtype indicando o que deu errado:

O exemplo abaixo verifica o campo subtype para determinar se a saída foi gerada com sucesso ou se você precisa lidar com uma falha:

for await (const msg of query({
  prompt: 'Extract contact info from the document',
  options: {
    outputFormat: {
      type: 'json_schema',
      schema: contactSchema
    }
  }
})) {
  if (msg.type === 'result') {
    if (msg.subtype === 'success' && msg.structured_output) {
      // Use a saída validada
      console.log(msg.structured_output)
    } else if (msg.subtype === 'error_max_structured_output_retries') {
      // Trate a falha - tente novamente com prompt mais simples, volte para não estruturado, etc.
      console.error('Could not produce valid output')
    }
  }
}

Dicas para evitar erros:

• Mantenha schemas focados. Schemas profundamente aninhados com muitos campos obrigatórios são mais difíceis de satisfazer. Comece simples e adicione complexidade conforme necessário.
• Corresponda schema à tarefa. Se a tarefa pode não ter todas as informações que seu schema requer, torne esses campos opcionais.
• Use prompts claros. Prompts ambíguas dificultam para o agente saber qual saída produzir.

Recursos relacionados

• Documentação de JSON Schema: aprenda sintaxe de JSON Schema para definir schemas complexos com objetos aninhados, arrays, enums e restrições de validação
• API Structured Outputs: use saídas estruturadas com a API Claude diretamente para requisições de uma única volta sem uso de ferramentas
• Ferramentas personalizadas: dê ao seu agente ferramentas personalizadas para chamar durante a execução antes de retornar saída estruturada