Claude Academy
Cargando

Datos estructurados con herramientas

Lección 308 min

Anteriormente en este curso, cubrimos cómo obtener salida estructurada de Claude usando pre-rellenos de mensajes y secuencias de parada. Aunque ese enfoque funciona bien y es fácil de configurar, podemos obtener una salida más confiable usando herramientas. Este método es más complejo de implementar, pero proporciona mejor consistencia al extraer datos estructurados como JSON.

¿Por qué aprender ambos enfoques?

Podrías preguntarte por qué no empezamos directamente con herramientas si son más confiables. La respuesta es simple: las herramientas requieren significativamente más configuración y complejidad. Tener ambas técnicas disponibles te da flexibilidad: a veces querrás el enfoque rápido basado en prompts, otras veces necesitarás la confiabilidad que proporcionan las herramientas.

Cómo funciona la salida estructurada basada en herramientas

El concepto central es sencillo: en lugar de pedirle a Claude que formatee su respuesta como JSON, creas una herramienta cuyos parámetros de entrada coinciden con la estructura exacta de los datos que deseas extraer. Claude entonces "llama" a esta herramienta con los datos extraídos como argumentos.

Este es el proceso:

  1. Escribe un esquema JSON que describa la estructura de los datos que deseas
  2. Crea una herramienta con ese esquema como su especificación de entrada
  3. Envía tus datos y el esquema de la herramienta a Claude
  4. Obliga a Claude a usar la herramienta con el parámetro toolChoice
  5. Extrae los datos estructurados de los argumentos de la llamada a la herramienta

El flujo se ve así: tu servidor envía un prompt pidiéndole a Claude que analice datos y llame a una herramienta específica. Claude responde con un mensaje de uso de herramientas que contiene los datos JSON extraídos. En ese punto, simplemente tomas los datos y terminas la conversación, sin necesidad de seguimiento.

Controlando el uso de herramientas

Cuando usas herramientas para salida estructurada, quieres garantizar que Claude use tu herramienta de extracción. El parámetro toolChoice te da tres opciones:

  • {"toolChoice": {"auto": {}}} - El modelo decide si necesita usar una herramienta (predeterminado)
  • {"toolChoice": {"any": {}}} - El modelo debe usar una herramienta, pero puede elegir cuál
  • {"toolChoice": {"tool": {"name": "tool-name"}}} - El modelo debe usar la herramienta especificada

Para salida estructurada, casi siempre querrás la tercera opción para asegurar que Claude use tu herramienta de extracción.

Ejemplo práctico

Supongamos que deseas extraer el título, el autor y los temas clave de un artículo. Primero, crearías un esquema de herramienta:

python
article_details_schema = {
    "toolSpec": {
        "name": "article_details",
        "description": "Extracts key information from an article",
        "inputSchema": {
            "json": {
                "type": "object",
                "properties": {
                    "title": {
                        "type": "string",
                        "description": "The title of the article"
                    },
                    "author": {
                        "type": "string", 
                        "description": "The author's name"
                    },
                    "topics": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "List of key topics mentioned"
                    }
                },
                "required": ["title", "author", "topics"]
            }
        }
    }
}

Luego llamarías a Claude con tus datos y lo obligarías a usar la herramienta. Nuestro helper chat toma el nombre de la herramienta directamente como su argumento tool_choice, así que no tienes que construir el objeto toolChoice anidado tú mismo:

python
messages = []
add_user_message(messages, f"""
Analyze the article below and extract key data. Then call the article_details tool.

<article_text>
{article_text}
</article_text>
""")

result = chat(messages, tools=[article_details_schema], tool_choice="article_details")

Claude responderá con un mensaje de uso de herramientas que contiene los datos extraídos en el formato exacto que especificaste. Los argumentos de la llamada a la herramienta contendrán tus datos JSON estructurados, listos para usar en tu aplicación.

Beneficios clave

  • Más confiable que la extracción basada en prompts
  • Estructura garantizada que coincide con tu esquema
  • No se necesitan pre-rellenos de mensajes ni secuencias de parada
  • Validación incorporada a través del esquema de la herramienta

La principal desventaja es la complejidad: necesitas escribir esquemas detallados y manejar las respuestas de las herramientas. Pero cuando necesitas una salida estructurada consistente y confiable, las herramientas son el camino a seguir.