Obtener salida estructurada de agentes

Las salidas estructuradas te permiten definir la forma exacta de los datos que deseas obtener de un agente. El agente puede usar cualquier herramienta que necesite para completar la tarea, y aún así obtendrás JSON validado que coincida con tu esquema al final. Define un JSON Schema para la estructura que necesitas, y el SDK garantiza que la salida coincida con él.

Para una seguridad de tipos completa, usa Zod (TypeScript) o Pydantic (Python) para definir tu esquema y obtener objetos fuertemente tipados.

¿Por qué salidas estructuradas?

Los agentes devuelven texto de forma libre por defecto, lo que funciona para chat pero no cuando necesitas usar la salida programáticamente. Las salidas estructuradas te dan datos tipados que puedes pasar directamente a tu lógica de aplicación, base de datos o componentes de UI.

Considera una aplicación de recetas donde un agente busca en la web y trae recetas. Sin salidas estructuradas, obtienes texto de forma libre que tendrías que analizar tú mismo. Con salidas estructuradas, defines la forma que deseas y obtienes datos tipados que puedes usar directamente en tu aplicación.

Inicio rápido

Para usar salidas estructuradas, define un JSON Schema que describa la forma de los datos que deseas, luego pásalo a query() a través de la opción outputFormat (TypeScript) u output_format (Python). Cuando el agente termina, el mensaje de resultado incluye un campo structured_output con datos validados que coinciden con tu esquema.

El ejemplo a continuación pide al agente que investigue Anthropic y devuelva el nombre de la empresa, año de fundación y sede como salida estructurada.

Esquemas seguros de tipos con Zod y Pydantic

En lugar de escribir JSON Schema a mano, puedes usar Zod (TypeScript) o Pydantic (Python) para definir tu esquema. Estas bibliotecas generan el JSON Schema para ti y te permiten analizar la respuesta en un objeto completamente tipado que puedes usar en todo tu código con autocompletado y verificación de tipos.

El ejemplo a continuación define un esquema para un plan de implementación de características con un resumen, lista de pasos (cada uno con nivel de complejidad) y riesgos potenciales. El agente planifica la característica y devuelve un objeto FeaturePlan tipado. Luego puedes acceder a propiedades como plan.summary e iterar sobre plan.steps con seguridad de tipos completa.

Beneficios:

Inferencia de tipos completa (TypeScript) e indicaciones de tipos (Python)
Validación en tiempo de ejecución con safeParse() o model_validate()
Mejores mensajes de error
Esquemas componibles y reutilizables

Configuración del formato de salida

La opción outputFormat (TypeScript) u output_format (Python) acepta un objeto con:

type: Establece en "json_schema" para salidas estructuradas
schema: Un objeto JSON Schema que define tu estructura de salida. Puedes generar esto desde un esquema Zod con z.toJSONSchema() o un modelo Pydantic con .model_json_schema()

El SDK admite características estándar de JSON Schema incluyendo todos los tipos básicos (object, array, string, number, boolean, null), enum, const, required, objetos anidados y definiciones $ref. Para la lista completa de características admitidas y limitaciones, consulta Limitaciones de JSON Schema.

Ejemplo: Agente de seguimiento de TODO

Este ejemplo demuestra cómo funcionan las salidas estructuradas con uso de herramientas de múltiples pasos. El agente necesita encontrar comentarios TODO en la base de código, luego buscar información de git blame para cada uno. Decide autónomamente qué herramientas usar (Grep para buscar, Bash para ejecutar comandos git) y combina los resultados en una única respuesta estructurada.

El esquema incluye campos opcionales (author y date) ya que la información de git blame podría no estar disponible para todos los archivos. El agente completa lo que puede encontrar y omite el resto.

Manejo de errores

La generación de salida estructurada puede fallar cuando el agente no puede producir JSON válido que coincida con tu esquema. Esto típicamente sucede cuando el esquema es demasiado complejo para la tarea, la tarea en sí es ambigua, o el agente alcanza su límite de reintentos intentando corregir errores de validación.

Cuando ocurre un error, el mensaje de resultado tiene un subtype que indica qué salió mal:

Subtype	Significado
`success`	La salida fue generada y validada exitosamente
`error_max_structured_output_retries`	El agente no pudo producir salida válida después de múltiples intentos

El ejemplo a continuación verifica el campo subtype para determinar si la salida fue generada exitosamente o si necesitas manejar un fallo:

Consejos para evitar errores:

Mantén esquemas enfocados. Los esquemas profundamente anidados con muchos campos requeridos son más difíciles de satisfacer. Comienza simple y agrega complejidad según sea necesario.
Haz coincidir el esquema con la tarea. Si la tarea podría no tener toda la información que tu esquema requiere, haz esos campos opcionales.
Usa prompts claros. Los prompts ambiguos hacen que sea más difícil para el agente saber qué salida producir.

Recursos relacionados

Documentación de JSON Schema: aprende la sintaxis de JSON Schema para definir esquemas complejos con objetos anidados, arrays, enums y restricciones de validación
API Structured Outputs: usa salidas estructuradas con la API de Claude directamente para solicitudes de un solo turno sin uso de herramientas
Herramientas personalizadas: proporciona a tu agente herramientas personalizadas para llamar durante la ejecución antes de devolver salida estructurada

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

// Define la forma de los datos que deseas obtener
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
    }
  }
})) {
  // El mensaje de resultado contiene structured_output con datos validados
  if (message.type === 'result' && message.structured_output) {
    console.log(message.structured_output)
    // { company_name: "Anthropic", founded_year: 2021, headquarters: "San Francisco, CA" }
  }
}

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

// Define esquema con 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>

// Convierte a JSON Schema
const schema = z.toJSONSchema(FeaturePlan)

// Usa en 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) {
    // Valida y obtén resultado completamente 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}`)
      })
    }
  }
}

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

// Define estructura para extracción 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']
}

// El agente usa Grep para encontrar TODOs, Bash para obtener información 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}`)
      }
    })
  }
}

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) {
      // Usa la salida validada
      console.log(msg.structured_output)
    } else if (msg.subtype === 'error_max_structured_output_retries') {
      // Maneja el fallo - reintenta con prompt más simple, retrocede a no estructurado, etc.
      console.error('Could not produce valid output')
    }
  }
}