Salidas estructuradas en el SDK

Obtén JSON estructurado y validado de flujos de trabajo de agentes. El SDK del Agente admite salidas estructuradas a través de Esquemas JSON, asegurando que tus agentes devuelvan datos exactamente en el formato que necesitas.

Por qué usar salidas estructuradas

Las salidas estructuradas proporcionan integración confiable y segura en tipos con tus aplicaciones:

• Estructura validada: Siempre recibe JSON válido que coincida con tu esquema
• Integración simplificada: No se necesita código de análisis o validación
• Seguridad de tipos: Úsalo con sugerencias de tipos de TypeScript o Python para seguridad de extremo a extremo
• Separación limpia: Define requisitos de salida separados de las instrucciones de tareas
• Autonomía de herramientas: El agente elige qué herramientas usar mientras garantiza el formato de salida

Cómo funcionan las salidas estructuradas

Características de Esquema JSON admitidas

El SDK del Agente admite las mismas características y limitaciones de Esquema JSON que Salidas Estructuradas de API.

Características clave admitidas:

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

Para detalles completos sobre características admitidas, limitaciones y soporte de patrones regex, consulta Limitaciones de Esquema JSON en la documentación de API.

Ejemplo: Agente de seguimiento de TODO

Aquí hay un ejemplo completo que muestra un agente que busca TODOs en código y extrae información de git blame:

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

El agente utiliza autónomamente las herramientas correctas (Grep, Bash) para recopilar información y devuelve datos validados.

Manejo de errores

Si el agente no puede producir una salida válida que coincida con tu esquema, recibirás un resultado de error:

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

• Documentación de Esquema JSON
• Salidas Estructuradas de API - Para llamadas de API únicas
• Herramientas personalizadas - Define herramientas para tus agentes
• Referencia del SDK de TypeScript - API completa de TypeScript
• Referencia del SDK de Python - API completa de Python