Uso de herramienta

Con los modelos Anthropic Claude, puede especificar una herramienta que el modelo puede usar para responder a un mensaje. Por ejemplo, puede especificar una herramienta que obtiene la canción más popular de una emisora de radio. Si el usuario pasa el mensaje ¿Cuál es la canción más popular en la emisora WZPZ?, el modelo determina que la herramienta que usted ha especificado puede ayudar a responder la pregunta. En su respuesta, el modelo solicita que usted ejecute la herramienta en su nombre. A continuación, ejecuta la herramienta y pasa el resultado de la herramienta al modelo, que generará una respuesta para el mensaje original. Para obtener más información, consulte Uso de herramientas (llamada a funciones) en la documentación de Anthropic Claude.

Especifique las herramientas que quiere poner a disposición de un modelo en el campo tools. El siguiente ejemplo es de una herramienta que obtiene la canción más popular de una emisora de radio.

[
    {
        "name": "top_song",
        "description": "Get the most popular song played on a radio station.",
        "input_schema": {
            "type": "object",
            "properties": {
                "sign": {
                    "type": "string",
                    "description": "The call sign for the radio station for which you want the most popular song. Example calls signs are WZPZ and WKRP."
                }
            },
            "required": [
                "sign"
            ]
        }
    }
]

Cuando el modelo necesita una herramienta para generar una respuesta a un mensaje, devuelve información sobre la herramienta solicitada y la entrada en la herramienta en el campo content del mensaje. También establece el motivo de parada de la respuesta a tool_use.

{
    "id": "msg_bdrk_01USsY5m3XRUF4FCppHP8KBx",
    "type": "message",
    "role": "assistant",
    "model": "claude-3-sonnet-20240229",
    "stop_sequence": null,
    "usage": {
        "input_tokens": 375,
        "output_tokens": 36
    },
    "content": [
        {
            "type": "tool_use",
            "id": "toolu_bdrk_01SnXQc6YVWD8Dom5jz7KhHy",
            "name": "top_song",
            "input": {
                "sign": "WZPZ"
            }
        }
    ],
    "stop_reason": "tool_use"
}

En su código, llame a la herramienta en nombre de la herramienta. A continuación, pase el resultado de la herramienta (tool_result) en un mensaje de usuario al modelo.

{
    "role": "user",
    "content": [
        {
            "type": "tool_result",
            "tool_use_id": "toolu_bdrk_01SnXQc6YVWD8Dom5jz7KhHy",
            "content": "Elemental Hotel"
        }
    ]
}

En su respuesta, el modelo utiliza el resultado de la herramienta para generar una respuesta para el mensaje original.

{
    "id": "msg_bdrk_012AaqvTiKuUSc6WadhUkDLP",
    "type": "message",
    "role": "assistant",
    "model": "claude-3-sonnet-20240229",
    "content": [
        {
            "type": "text",
            "text": "According to the tool, the most popular song played on radio station WZPZ is \"Elemental Hotel\"."
        }
    ],
    "stop_reason": "end_turn"
}

Transmisión de herramientas detallada

La transmisión de herramientas detallada es una capacidad del modelo Anthropic Claude disponible con Claude Sonnet 4.5, Claude Haiku 4.5, Claude Sonnet 4 y Claude Opus 4. Con la transmisión de herramientas detallada, los desarrolladores de Claude pueden transmitir los parámetros de uso de las herramientas sin necesidad de almacenar en búfer ni validar los objetos JSON, lo que reduce la latencia necesaria para empezar a recibir parámetros de gran tamaño.

Para utilizar esta característica, simplemente añada el encabezado fine-grained-tool-streaming-2025-05-14 a una solicitud de uso de herramienta.

A continuación, se muestra un ejemplo de cómo especificar el encabezado de transmisión de herramienta detallada:

{
  "anthropic_version": "bedrock-2023-05-31",
  "max_tokens": 1024,
  "anthropic_beta": ["fine-grained-tool-streaming-2025-05-14"],
  "messages": [
    {
      "role": "user",
      "content": "Can you write a long poem and make a file called poem.txt?"
    }
  ],
  "tools": [
    {
      "name": "make_file",
      "description": "Write text to a file",
      "input_schema": {
        "type": "object",
        "properties": {
          "filename": {
            "type": "string",
            "description": "The filename to write text to"
          },
          "lines_of_text": {
            "type": "array",
            "description": "An array of lines of text to write to the file"
          }
        },
        "required": [
          "filename",
          "lines_of_text"
        ]
      }
    }
  ]
}

En este ejemplo, la transmisión de herramienta detallada permite a Claude transmitir las líneas de un poema largo a la llamada de herramienta make_file sin necesidad de almacenarlo en búfer para validar si el parámetro lines_of_text es un JSON válido. Esto significa que puede ver el flujo de parámetros a medida que llega, sin tener que esperar a que todo el parámetro se almacene en búfer y se valide.

Con la transmisión de herramientas detallada, los fragmentos de uso de herramienta comienzan a transmitirse más rápido y, a menudo, son más largos y contienen menos saltos de palabras. Esto se debe a las diferencias en el comportamiento de fragmentación.

Por ejemplo, sin transmisión detallada (15 segundos de retraso):

Chunk 1: '{"'
Chunk 2: 'query": "Ty'
Chunk 3: 'peScri'
Chunk 4: 'pt 5.0 5.1 '
Chunk 5: '5.2 5'
Chunk 6: '.3'
Chunk 8: ' new f'
Chunk 9: 'eatur'
...

Con transmisión detallada (3 segundos de retraso):

Chunk 1: '{"query": "TypeScript 5.0 5.1 5.2 5.3'
Chunk 2: ' new features comparison'

Uso de computadora (Beta)

Uso del equipo es una capacidad del modelo Anthropic Claude (en versión beta) disponible únicamente con Claude 3.5 Sonnet v2, Claude Sonnet 4.5, Claude Haiku 4.5, Claude 3.7 Sonnet, Claude Sonnet 4 y Claude Opus 4. Con Uso de computadora, Claude puede ayudarlo a automatizar tareas mediante acciones básicas de la GUI.

La API de uso del equipo ofrece varias herramientas de uso del equipo predefinidas para su uso. A continuación, podrá crear una petición en la solicitud, como “envía un correo electrónico a Ben con las notas de mi última reunión” y una captura de pantalla (si es necesario). La respuesta contiene una lista de acciones de tool_use en formato JSON (por ejemplo, scroll_down, left_button_press, screenshot). El código ejecuta las acciones de la computadora y proporciona a Claude una captura de pantalla que muestra los resultados (cuando se solicita).

Desde la versión Claude 3.5 v2, el parámetro de herramientas se ha actualizado para que acepte tipos de herramientas polimórficas; se ha añadido una propiedad tool.type para distinguirlos. type es opcional; si se omite, se asume que se trata de una herramienta personalizada (anteriormente, era el único tipo de herramienta compatible). Para acceder al uso del equipo, debe usar el parámetro anthropic_beta, con la enumeración correspondiente, cuyo valor depende de la versión del modelo que se utilice. Para obtener más información, consulte la siguiente tabla.

Solo las solicitudes realizadas con este parámetro y enumeración pueden usar las herramientas de uso del equipo. Se puede especificar de la siguiente manera: "anthropic_beta": ["computer-use-2025-01-24"].

Para obtener más información, consulte Uso de computadora (beta) en la documentación de Anthropic.

El siguiente es un ejemplo de respuesta donde se supone que la solicitud contiene una captura de pantalla de su escritorio con un icono de Firefox.

{
    "id": "msg_123",
    "type": "message",
    "role": "assistant",
    "model": "anthropic.claude-3-5-sonnet-20241022-v2:0",
    "content": [
        {
            "type": "text",
            "text": "I see the Firefox icon. Let me click on it and then navigate to a weather website."
        },
        {
            "type": "tool_use",
            "id": "toolu_123",
            "name": "computer",
            "input": {
                "action": "mouse_move",
                "coordinate": [
                    708,
                    736
                ]
            }
        },
        {
            "type": "tool_use",
            "id": "toolu_234",
            "name": "computer",
            "input": {
                "action": "left_click"
            }
        }
    ],
    "stop_reason": "tool_use",
    "stop_sequence": null,
    "usage": {
        "input_tokens": 3391,
        "output_tokens": 132
    }
}

Herramientas definidas por Anthropic

Anthropic proporciona un conjunto de herramientas que permiten a determinados modelos Claude utilizar los equipos de forma eficaz. Al especificar una herramienta definida por Anthropic, los campos description y tool_schema no son necesarios ni están permitidos. Las herramientas definidas por Anthropic vienen definidas por Anthropic, pero debe evaluar explícitamente los resultados de la herramienta y devolver el elemento tool_results en Claude. Como ocurre con cualquier herramienta, el modelo no ejecuta automáticamente la herramienta. Cada herramienta definida por Anthropic tiene versiones optimizadas para modelos Claude 3.5 Sonnet (nuevos) y Claude 3.7 Sonnet específicos:

{ 
    "type": "text_editor_20250124", 
    "name": "str_replace_based_edit_tool" 
}

{ 
    "type": "computer_20250124", 
    "name": "computer" 
}

{ 
    "type": "text_editor_20250124", 
    "name": "str_replace_editor"
}

{ 
    "type": "bash_20250124", 
    "name": "bash" 
}

{ 
    "type": "text_editor_20241022", 
    "name": "str_replace_editor"
}

{ 
    "type": "bash_20241022", 
    "name": "bash"
}

{ 
    "type": "computer_20241022", 
    "name": "computer"
}

El campo type identifica la herramienta y sus parámetros con fines de validación; el campo name es el nombre de la herramienta expuesto al modelo.

Si desea solicitar al modelo que utilice una de estas herramientas, puede hacer referencia explícita a la herramienta mediante el campo name. El campo name debe ser único en la lista de herramientas; no se puede definir una herramienta con el mismo name que una herramienta definida por Anthropic en la misma llamada a la API.

Borrado automático de llamadas a herramientas (beta)

Claude Sonnet 4.5 admite una nueva característica beta que borra automáticamente los resultados de uso de herramientas antiguas a medida que se acercan los límites de tokens, lo que permite una gestión del contexto más eficiente en escenarios de uso de herramientas de varios turnos. Para utilizar el borrado del uso de herramientas, debe añadir context-management-2025-06-27 a la lista de encabezados beta del parámetro de solicitud anthropic_beta. También tendrá que especificar el uso de clear_tool_uses_20250919 y seleccionar alguna de las siguientes opciones de configuración.

Estos son los controles disponibles para la estrategia de administración del contexto de clear_tool_uses_20250919. Todos son opcionales o tienen valores predeterminados:

Si se utiliza Claude Sonnet 4.5 con borrado automático de llamadas a herramientas, la respuesta incluye información adicional sobre la administración del contexto:

{
    "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
    "type": "message",
    "role": "assistant",
    "content": [...],
    ...
    "usage": {...},
    "context_management": {
        "applied_edits": [
            {
                "type": "clear_tool_uses_20250919",
                "cleared_tool_uses": 8,  # Number of tool use/result pairs that were cleared
                "cleared_input_tokens": 50000  # Total number of input tokens removed from the prompt
            }
        ]
    }
}

Herramienta de memoria (beta)

Claude Sonnet 4.5 incluye una nueva herramienta de memoria que ofrece a los clientes una forma de administrar la memoria en las conversaciones. Con esta característica, los clientes pueden permitir que Claude recupere información fuera de la ventana contextual proporcionando acceso a un directorio local. Estará disponible como característica beta. Para utilizar esta característica, debe utilizar el encabezado beta context-management-2025-06-27.

Definición de herramienta:

{
  "type": "memory_20250818",
  "name": "memory"
}

Solicitud de ejemplo:

{
    "max_tokens": 2048,
    "anthropic_version": "bedrock-2023-05-31",
    "anthropic_beta": ["context-management-2025-06-27"],
    "tools": [{
        "type": "memory_20250818",
        "name": "memory"
    }],
    "messages": [
        {
            "role": "user",
            "content": [{"type": "text", "text": "Remember that my favorite color is blue and I work at Amazon?"}]
        }
    ]
}

Respuesta de ejemplo:

{
    "id": "msg_vrtx_014mQ5ficCRB6PEa5k5sKqHd",
    "type": "message",
    "role": "assistant",
    "model": "claude-sonnet-4-20250514",
    "content": [
        {
            "type": "text",
            "text": "I'll start by checking your memory directory and then record this important information about you."
        },
        {
            "type": "tool_use",
            "id": "toolu_vrtx_01EU1UrCDigyPMRntr3VYvUB",
            "name": "memory",
            "input": {
                "command": "view",
                "path": "/memories"
            }
        }
    ],
    "stop_reason": "tool_use",
    "stop_sequence": null,
    "usage": {
        "input_tokens": 1403,
        "cache_creation_input_tokens": 0,
        "cache_read_input_tokens": 0,
        "output_tokens": 87
    },
    "context_management": {
        "applied_edits": []
    }
}

Consideraciones relacionadas con el costo del uso de herramientas

Los precios de las solicitudes de uso de herramientas se basan en los siguientes factores:

El precio de las herramientas es el mismo que el de todas las demás solicitudes de la API Claude, pero incluyen tokens adicionales por solicitud. Los tokens adicionales derivados del uso de herramientas provienen de lo siguiente:

Cuando se utilizan herramientas, los modelos Anthropic incluyen automáticamente una petición de sistema especial que permite el uso de herramientas. El número de tokens de uso de herramientas necesarios para cada modelo se indica en la siguiente tabla. En esta tabla no se incluyen los tokens adicionales descritos anteriormente. Tenga en cuenta que en esta tabla se supone que se proporciona al menos una herramienta. Si no se proporciona ninguna herramienta, la opción de herramienta “none” utiliza 0 tokens de peticiones del sistema adicionales.