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)

La eliminación automática de llamadas a herramientas es una función del modelo Anthropic Claude (en versión beta). Con esta función, Claude puede borrar automáticamente los resultados de uso de herramientas antiguas a medida que se acerque a los límites simbólicos, 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 las siguientes opciones de configuración clear_tool_uses_20250919 y elegir entre ellas.

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:

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.

Herramienta de búsqueda de herramientas (beta)

La herramienta de búsqueda de herramientas Claude permite trabajar con cientos o incluso miles de herramientas sin cargar todas sus definiciones por adelantado en la ventana de contexto. En lugar de declarar todas las herramientas de forma inmediata, puede marcarlas defer_loading: true y buscar Claude y cargar solo las herramientas que necesita mediante el mecanismo de búsqueda de herramientas.

Para acceder a esta función, debe utilizar el encabezado betatool-search-tool-2025-10-19. Tenga en cuenta que, actualmente, esta función solo está disponible a través de InvokeModely InvokeModelWithResponseStream APIs.

Definición de herramienta:

{
    "type": "tool_search_tool_regex",
    "name": "tool_search_tool_regex"
}

Ejemplo de solicitud:

{
    "anthropic_version": "bedrock-2023-05-31",
    "anthropic_beta": [
        "tool-search-tool-2025-10-19"
    ],
    "max_tokens": 4096,
    "tools": [{
            "type": "tool_search_tool_regex",
            "name": "tool_search_tool_regex"
        },
        {
            "name": "get_weather",
            "description": "Get current weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"]
                    }
                },
                "required": ["location"]
            },
            "defer_loading": true
        },
        {
            "name": "search_files",
            "description": "Search through files in the workspace",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string"
                    },
                    "file_types": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    }
                },
                "required": ["query"]
            },
            "defer_loading": true
        }
    ],
    "messages": [{
        "role": "user",
        "content": "What's the weather in Seattle?"
    }]
}

Ejemplo de respuesta

{
    "role": "assistant",
    "content": [{
            "type": "text",
            "text": "I'll search for the appropriate tools to help with this task."
        },
        {
            "type": "server_tool_use",
            "id": "srvtoolu_01ABC123",
            "name": "tool_search_tool_regex",
            "input": {
                "pattern": "weather"
            }
        },
        {
            "type": "tool_search_tool_result",
            "tool_use_id": "srvtoolu_01ABC123",
            "content": {
                "type": "tool_search_tool_search_result",
                "tool_references": [{
                    "type": "tool_reference",
                    "tool_name": "get_weather"
                }]
            }
        },
        {
            "type": "text",
            "text": "Now I can check the weather."
        },
        {
            "type": "tool_use",
            "id": "toolu_01XYZ789",
            "name": "get_weather",
            "input": {
                "location": "Seattle",
                "unit": "fahrenheit"
            }
        }
    ],
    "stop_reason": "tool_use"
}

Ejemplo de streaming

# Event 1: content_block_start(with complete server_tool_use block) {
    "type": "content_block_start",
    "index": 0,
    "content_block": {
        "type": "server_tool_use",
        "id": "srvtoolu_01ABC123",
        "name": "tool_search_tool_regex"
    }
}

# Event 2: content_block_delta(input JSON streamed) {
    "type": "content_block_delta",
    "index": 0,
    "delta": {
        "type": "input_json_delta",
        "partial_json": "{\"regex\": \".*weather.*\"}"
    }
}

# Event 3: content_block_stop(tool_use complete) {
    "type": "content_block_stop",
    "index": 0
}

# Event 4: content_block_start(COMPLETE result in single chunk) {
    "type": "content_block_start",
    "index": 1,
    "content_block": {
        "type": "tool_search_tool_result",
        "tool_use_id": "srvtoolu_01ABC123",
        "content": {
            "type": "tool_search_tool_search_result",
            "tool_references": [{
                "type": "tool_reference",
                "tool_name": "get_weather"
            }]
        }
    }
}

# Event 5: content_block_stop(result complete) {
    "type": "content_block_stop",
    "index": 1
}

Herramientas de búsqueda personalizadas

Puede implementar herramientas de búsqueda de herramientas personalizadas (por ejemplo, mediante incrustaciones) definiendo una herramienta que devuelva bloques. tool_reference La herramienta personalizada debe tenerla, defer_loading: false mientras que otras herramientas deberían tenerla. defer_loading: true Cuando definas tu propia herramienta de búsqueda de herramientas, debería arrojar un resultado de la herramienta que contenga bloques de tool_reference contenido que apunten a las herramientas que deseas Claude usar.

El formato de respuesta de resultados de la herramienta de búsqueda de herramientas definido por el cliente esperado:

{
    "type": "tool_result",
    "tool_use_id": "toolu_01ABC123",
    "content": [{
            "type": "tool_reference",
            "tool_name": "get_weather"
        },
        {
            "type": "tool_reference",
            "tool_name": "weather_forecast"
        }
    ]
}

tool_nameDebe coincidir con una herramienta definida en la solicitud. defer_loading: true Claude tendrá entonces acceso a los esquemas completos de esas herramientas.

Herramientas de búsqueda personalizadas: ejemplo detallado

Puede implementar herramientas de búsqueda de herramientas personalizadas (por ejemplo, mediante incrustaciones o búsquedas semánticas) definiendo una herramienta que devuelva bloques. tool_reference Esto permite mecanismos sofisticados de descubrimiento de herramientas que van más allá de la coincidencia de expresiones regulares.

Ejemplo de solicitud con un TST personalizado:

{
    "model": "claude-sonnet-4-5-20250929",
    "anthropic_version": "bedrock-2023-05-31",
    "anthropic_beta": ["tool-search-tool-2025-10-19"],
    "max_tokens": 4096,
    "tools": [{
            "name": "semantic_tool_search",
            "description": "Search for available tools using semantic similarity. Returns the most relevant tools for the given query.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Natural language description of what kind of tool is needed"
                    },
                    "top_k": {
                        "type": "integer",
                        "description": "Number of tools to return (default: 5)"
                    }
                },
                "required": ["query"]
            },
            "defer_loading": false
        },
        {
            "name": "get_weather",
            "description": "Get current weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"]
                    }
                },
                "required": ["location"]
            },
            "defer_loading": true
        },
        {
            "name": "search_flights",
            "description": "Search for available flights between locations",
            "input_schema": {
                "type": "object",
                "properties": {
                    "origin": {
                        "type": "string"
                    },
                    "destination": {
                        "type": "string"
                    },
                    "date": {
                        "type": "string"
                    }
                },
                "required": ["origin", "destination", "date"]
            },
            "defer_loading": true
        }
    ],
    "messages": [{
        "role": "user",
        "content": "What's the weather forecast in Seattle for the next 3 days?"
    }]
}

Claudesu respuesta (llamando a un TST personalizado):

{
    "role": "assistant",
    "content": [{
            "type": "text",
            "text": "I'll search for the appropriate tools to help with weather information."
        },
        {
            "type": "tool_use",
            "id": "toolu_01ABC123",
            "name": "semantic_tool_search",
            "input": {
                "query": "weather forecast multiple days",
                "top_k": 3
            }
        }
    ],
    "stop_reason": "tool_use"
}

Resultado de la herramienta proporcionada por el cliente

Tras realizar una búsqueda semántica en la biblioteca de herramientas, el cliente devuelve las referencias de herramientas coincidentes:

{
    "role": "user",
    "content": [{
        "type": "tool_search_tool_result",
        "tool_use_id": "toolu_01ABC123",
        "content": {
            "type": "tool_search_tool_search_result",
            "tool_references": [{
                "type": "tool_reference",
                "tool_name": "get_weather"
            }]
        }
    }]
}

Claudesu seguimiento (mediante la herramienta descubierta)

{
    "role": "assistant",
    "content": [{
            "type": "text",
            "text": "I found the forecast tool. Let me get the weather forecast for Seattle."
        },
        {
            "type": "tool_use",
            "id": "toolu_01DEF456",
            "name": "get_weather",
            "input": {
                "location": "Seattle, WA"
            }
        }
    ],
    "stop_reason": "tool_use"
}

Ejemplos de uso de herramientas (beta)

Claude OpusLa versión 4.5 admite ejemplos proporcionados por los usuarios en las definiciones de herramientas para aumentar el rendimiento Claude de uso de las herramientas. Puede proporcionar ejemplos como llamadas a funciones completas, formateadas exactamente como lo estarían las salidas LLM reales, sin necesidad de traducirlos a otro formato. Para utilizar esta función, debe pasar el encabezado beta. tool-examples-2025-10-29

Ejemplo de definición de herramienta:

{
    "name": "get_weather",
    "description": "Get the current weather in a given location",
    "input_schema": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA"
            },
            "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"],
                "description": "Temperature unit"
            }
        },
        "required": ["location"]
    },
    "input_examples": [{
            "location": "San Francisco, CA",
            "unit": "fahrenheit"
        },
        {
            "location": "Tokyo, Japan",
            "unit": "celsius"
        },
        {
            "location": "New York, NY"
        }
    ]
}

Ejemplos de errores:

// Invalid: Example doesn't match schema (missing required field)
{
    "type": "invalid_request_error",
    "message": "Tool 'get_weather' input_examples[0] is invalid: Missing required property 'location'"
}

// Invalid: Example has wrong type for field
{
    "type": "invalid_request_error",
    "message": "Tool 'search_products' input_examples[1] is invalid: Property 'filters.price_range.min' must be a number, got string"
}

// Invalid: input_examples on server-side tool
{
    "type": "invalid_request_error",
    "message": "input_examples is not supported for server-side tool"
}