Cargando

Datos estructurados con herramientas

Lección 308 min
Cargando

Anteriormente en este curso, vimos cómo obtener salida estructurada de Claude usando prerrellenos de mensajes y secuencias de parada. Si bien 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 una configuración y complejidad considerablemente mayores. Tener ambas técnicas disponibles te da flexibilidad: a veces querrás el enfoque rápido basado en indicaciones, 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 exactamente con la estructura de datos que quieres extraer. Claude luego "llama" a esta herramienta con los datos extraídos como argumentos.

Un financial_analysis_schema para una herramienta analyze_financial_statement: "balance" entero requerido y arreglo "key_insights".

Este es el proceso:

  1. Escribe un esquema JSON que describa la estructura de 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

Nuestro servidor envía a Claude una indicación para analizar un estado financiero y llamar a la herramienta financial_analysis, junto con su esquema.

El flujo se ve así: tu servidor envía una indicación pidiendo a Claude que analice datos y llame a una herramienta específica. Claude responde con un mensaje de uso de herramienta que contiene los datos JSON extraídos. En ese punto, simplemente tomas los datos y finalizas la conversación; no se necesita 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:

Celda de notebook pidiéndole a Claude un artículo académico de un párrafo con título y nombre de autor, y la respuesta de texto largo.

  • {"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 quieres extraer el título, autor y 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 ayudante chat toma el nombre de la herramienta directamente como su argumento tool_choice, así que no tienes que construir tú mismo el objeto anidado toolChoice:

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 herramienta 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 indicaciones
  • Estructura garantizada que coincide con tu esquema
  • No se necesitan prerrellenos 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.