Aquí hay algunos ejemplos de código que demuestran varios patrones y técnicas de uso de herramientas. Por motivos de brevedad, las herramientas son herramientas simples y las descripciones de las herramientas son más cortas de lo que sería ideal para garantizar el mejor rendimiento. Consulte especificación de herramientas para obtener más información.

​
Herramienta única

Este ejemplo muestra una situación básica de una sola herramienta, utilizando una herramienta get_weather.

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "tools": [{
        "name": "get_weather",
        "description": "Obtener el clima actual en una ubicación dada",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "La ciudad y el estado, por ejemplo, San Francisco, CA"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "La unidad de temperatura, ya sea \"celsius\" o \"fahrenheit\""
                }
            },
            "required": ["location"]
        }
    }],
    "messages": [{"role": "user", "content": "¿Cómo está el clima en San Francisco?"}]
}'

Claude devolverá una respuesta similar a:

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-opus-20240229",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Necesito llamar a la función get_weather, y el usuario quiere SF, que probablemente sea San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9", 
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

Luego, deberías ejecutar la función get_weather con la entrada proporcionada y devolver el resultado en un nuevo mensaje de user:

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Obtener el clima actual en una ubicación dada",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "La ciudad y el estado, por ejemplo, San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "La unidad de temperatura, ya sea \"celsius\" o \"fahrenheit\""
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "¿Cómo está el clima en San Francisco?"
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "<thinking>Necesito usar get_weather, y el usuario quiere SF, que probablemente sea San Francisco, CA.</thinking>"
                },
                {
                    "type": "tool_use",
                    "id": "toolu_01A09q90qw90lq917835lq9",
                    "name": "get_weather",
                    "input": {
                        "location": "San Francisco, CA",
                        "unit": "celsius"
                    }
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
                    "content": "15 grados"
                }
            ]
        }
    ]
}'

Esto imprimirá la respuesta final de Claude, incorporando los datos del clima:

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-opus-20240229",
  "stop_reason": "stop_sequence",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "El clima actual en San Francisco es de 15 grados Celsius (59 grados Fahrenheit). ¡Es un día fresco en la ciudad junto a la bahía!"
    }
  ]
}

​
Información faltante

Si el prompt del usuario no incluye suficiente información para completar todos los parámetros requeridos para una herramienta, es mucho más probable que Claude 3 Opus reconozca que falta un parámetro y lo solicite. Claude 3 Sonnet puede preguntar, especialmente cuando se le indica que piense antes de generar una solicitud de herramienta. Pero también puede hacer todo lo posible para inferir un valor razonable.

Por ejemplo, usando la herramienta get_weather anterior, si le preguntas a Claude “¿Cómo está el clima?” sin especificar una ubicación, Claude, particularmente Claude 3 Sonnet, puede adivinar las entradas de las herramientas:

JSON
{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "get_weather", 
  "input": {"location": "New York, NY", "unit": "fahrenheit"}
}

Este comportamiento no está garantizado, especialmente para prompts más ambiguos y para modelos menos inteligentes que Claude 3 Opus. Si Claude 3 Opus no tiene suficiente contexto para completar los parámetros requeridos, es mucho más probable que responda con una pregunta de aclaración en lugar de hacer una llamada a la herramienta.

​
Múltiples herramientas

Puedes proporcionar a Claude múltiples herramientas para elegir en una sola solicitud. Aquí hay un ejemplo con una herramienta get_weather y una herramienta get_time, junto con una consulta del usuario que solicita ambas.

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "tools": [{
        "name": "get_weather",
        "description": "Obtener el clima actual en una ubicación dada",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "La ciudad y el estado, por ejemplo, San Francisco, CA"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "La unidad de temperatura, ya sea 'celsius' o 'fahrenheit'"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Obtener la hora actual en una zona horaria dada",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "El nombre de la zona horaria IANA, por ejemplo, America/Los_Angeles"
                }
            },
            "required": ["timezone"]
        }
    }],
    "messages": [{
        "role": "user",
        "content": "¿Cómo está el clima ahora mismo en Nueva York? ¿Y qué hora es allí?"
    }]
}'

En este caso, Claude probablemente intentará usar dos herramientas separadas, una a la vez: get_weather y luego get_time, para responder completamente la pregunta del usuario. Sin embargo, ocasionalmente también generará dos bloques tool_use a la vez, particularmente si no dependen entre sí. Deberías ejecutar cada herramienta y devolver sus resultados en bloques tool_result separados dentro de un solo mensaje de user.

​
Herramientas secuenciales

Algunas tareas pueden requerir llamar a múltiples herramientas en secuencia, utilizando la salida de una herramienta como entrada para otra. En tal caso, Claude llamará a una herramienta a la vez. Si se le indica que llame a todas las herramientas a la vez, es probable que Claude adivine los parámetros para las herramientas más adelante en la secuencia si dependen de los resultados de las herramientas anteriores.

Aquí hay un ejemplo de usar una herramienta get_location para obtener la ubicación del usuario y luego pasar esa ubicación a la herramienta get_weather:

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_location",
            "description": "Obtener la ubicación actual del usuario basada en su dirección IP. Esta herramienta no tiene parámetros o argumentos.",
            "input_schema": {
                "type": "object",
                "properties": {}
            }
        },
        {
            "name": "get_weather",
            "description": "Obtener el clima actual en una ubicación dada",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "La ciudad y el estado, por ejemplo, San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "La unidad de temperatura, ya sea 'celsius' o 'fahrenheit'"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [{
        "role": "user",
        "content": "¿Cómo está el clima donde estoy?"
    }]
}'

En este caso, Claude primero llamaría a la herramienta get_location para obtener la ubicación del usuario. Después de que devuelvas la ubicación en un tool_result, Claude llamaría a get_weather con esa ubicación para obtener la respuesta final.

La conversación completa podría verse así:

RolContenido
Usuario¿Cómo está el clima donde estoy?
Asistente<thinking>Para responder esto, primero necesito determinar la ubicación del usuario usando la herramienta get_location. Luego puedo pasar esa ubicación a la herramienta get_weather para encontrar el clima actual allí.</thinking>[Uso de herramienta para get_location]
Usuario[Resultado de herramienta para get_location con id coincidente y resultado de San Francisco, CA]
Asistente[Uso de herramienta para get_weather con la siguiente entrada]{ “location”: “San Francisco, CA”, “unit”: “fahrenheit” }
Usuario[Resultado de herramienta para get_weather con id coincidente y resultado de “59°F (15°C), mayormente nublado”]
AsistenteBasado en tu ubicación actual en San Francisco, CA, el clima en este momento es de 59°F (15°C) y mayormente nublado. Es un día bastante fresco y nublado en la ciudad. Puede que quieras llevar una chaqueta ligera si vas a salir.

Este ejemplo demuestra cómo Claude puede encadenar múltiples llamadas a herramientas para responder una pregunta que requiere recopilar datos de diferentes fuentes. Los pasos clave son:

  1. Claude primero se da cuenta de que necesita la ubicación del usuario para responder la pregunta sobre el clima, así que llama a la herramienta get_location.
  2. El usuario (es decir, el código del cliente) ejecuta la función get_location real y devuelve el resultado “San Francisco, CA” en un bloque tool_result.
  3. Con la ubicación ahora conocida, Claude procede a llamar a la herramienta get_weather, pasando “San Francisco, CA” como el parámetro location (así como un parámetro unit adivinado, ya que unit no es un parámetro requerido).
  4. El usuario nuevamente ejecuta la función get_weather real con los argumentos proporcionados y devuelve los datos del clima en otro bloque tool_result.
  5. Finalmente, Claude incorpora los datos del clima en una respuesta en lenguaje natural a la pregunta original.

​
Uso de herramientas con cadena de pensamiento

Por defecto, se indica a Claude 3 Opus que piense antes de responder una consulta de uso de herramienta para determinar mejor si una herramienta es necesaria, qué herramienta usar y los parámetros apropiados. Se indica a Claude 3 Sonnet y Claude 3 Haiku que intenten usar herramientas tanto como sea posible y es más probable que llamen a una herramienta innecesaria o infieran parámetros faltantes. Para indicar a Sonnet o Haiku que evalúen mejor la consulta del usuario antes de hacer llamadas a herramientas, se puede usar el siguiente prompt:

Prompt de cadena de pensamiento

Responde la solicitud del usuario utilizando herramientas relevantes (si están disponibles). Antes de llamar a una herramienta, haz un análisis dentro de las etiquetas \<thinking>\</thinking>. Primero, piensa en cuál de las herramientas proporcionadas es la herramienta relevante para responder la solicitud del usuario. Segundo, revisa cada uno de los parámetros requeridos de la herramienta relevante y determina si el usuario ha proporcionado directamente o ha dado suficiente información para inferir un valor. Al decidir si el parámetro puede ser inferido, considera cuidadosamente todo el contexto para ver si respalda un valor específico. Si todos los parámetros requeridos están presentes o pueden ser inferidos razonablemente, cierra la etiqueta de pensamiento y procede con la llamada a la herramienta. PERO, si uno de los valores para un parámetro requerido falta, NO invoques la función (ni siquiera con valores de relleno para los parámetros faltantes) y en su lugar, pídele al usuario que proporcione los parámetros faltantes. NO pidas más información sobre parámetros opcionales si no se proporciona.

​
Modo JSON

Puedes usar herramientas para hacer que Claude produzca una salida JSON que siga un esquema, incluso si no tienes intención de ejecutar esa salida a través de una herramienta o función.

Al usar herramientas de esta manera:

  • Por lo general, deseas proporcionar una única herramienta
  • Debes establecer tool_choice (consulta Forzar el uso de herramientas) para instruir al modelo a usar explícitamente esa herramienta
  • Recuerda que el modelo pasará la input a la herramienta, por lo que el nombre de la herramienta y la descripción deben ser desde la perspectiva del modelo.

Lo siguiente usa una herramienta record_summary para describir una imagen siguiendo un formato particular.

#!/bin/bash
IMAGE_URL="https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
IMAGE_MEDIA_TYPE="image/jpeg"
IMAGE_BASE64=$(curl "$IMAGE_URL" | base64)

curl https://api.anthropic.com/v1/messages \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --data \
'{
    "model": "claude-3-sonnet-20240229",
    "max_tokens": 1024,
    "tools": [{
        "name": "record_summary",
        "description": "Registrar resumen de una imagen usando JSON bien estructurado.",
        "input_schema": {
            "type": "object",
            "properties": {
                "key_colors": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
"r": { "type": "number", "description": "valor rojo [0.0, 1.0]" },
"g": { "type": "number", "description": "valor verde [0.0, 1.0]" },
"b": { "type": "number", "description": "valor azul [0.0, 1.0]" },
"name": { "type": "string", "description": "Nombre de color legible para humanos en snake_case, por ejemplo, \"olive_green\" o \"turquoise\"" }
                        },
                        "required": [ "r", "g", "b", "name" ]
                    },
                    "description": "Colores clave en la imagen. Limitar a menos de cuatro."
                },
                "description": {
                    "type": "string",
                    "description": "Descripción de la imagen. Una o dos oraciones máximo."
                },
                "estimated_year": {
                    "type": "integer",
                    "description": "Año estimado en que se tomó la imagen, si es una foto. Solo establecer esto si la imagen parece ser no ficticia. ¡Estimaciones aproximadas están bien!"
                }
            },
            "required": [ "key_colors", "description" ]
        }
    }],
    "tool_choice": {"type": "tool", "name": "record_summary"},
    "messages": [
        {"role": "user", "content": [
            {"type": "image", "source": {
                "type": "base64",
                "media_type": "'$IMAGE_MEDIA_TYPE'",
                "data": "'$IMAGE_BASE64'"
            }},
            {"type": "text", "text": "Describe esta imagen."}
        ]}
    ]
}'
ResumenPrecios y tokens por el uso de herramientas