Uso de la herramienta Anthropic Claude

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"
}

Fine-grained transmisión de herramientas

Fine-grained la transmisión de herramientas es una capacidad Anthropic Claude modelo disponible con Claude Sonnet 4.5Claude 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)

El uso de ordenadores es una familia de Anthropic Claude herramientas (en versión beta) para automatizar las tareas de la interfaz gráfica de usuario (GUI). Para obtener una descripción general, el formulario de Bedrock-specific solicitud de Amazon y un ejemplo completo, consulteUtilice herramientas informáticas para automatizar las tareas de la interfaz gráfica de usuario con los modelos de Amazon Bedrock. Para saber qué modelos admiten el uso de ordenadores en cada punto final, consulte la tabla de capacidades y características de cada uno de ellosModelos de un vistazo.

Para permitir el uso del ordenador en una solicitud, configúrelo en una versión anthropic_beta para uso del ordenador e incluya una entrada de herramienta que type coincida con esa versión. Los emparejamientos válidos son:

Cada tipo de herramienta solo funciona con un subconjunto específico de modelos. Al enviar un tipo de herramienta que no es compatible 400 invalid_request_error con un modelo, se devuelve un mensaje como'claude-opus-4-7' does not support tool types: computer_20241022. Confirme la compatibilidad en la tabla de capacidades y características del modelo antes de enviar las solicitudes.

Para obtener información sobre el protocolo de la herramienta subyacente, el vocabulario completo de acción y las instrucciones de ingeniería rápida, consulte Uso del ordenador en la Anthropic documentación.

Conjuntos de herramientas para clientes

Algunos Claude modelos aceptan dos conjuntos de herramientas de cliente incluidos como valores. tools[].type Un conjunto de herramientas agrupa un grupo relacionado de herramientas de cliente en un solo tipo, por lo que no es necesario declarar cada herramienta de forma individual. No se anthropic_beta requiere ningún valor.

Al igual que ocurre con las herramientas de cliente individuales, el modelo solicita acciones pero no las ejecuta. Ejecuta cada acción solicitada y devuelve untool_result. Al enviar un tipo de conjunto de herramientas que no admite un modelo, se devuelve un400 invalid_request_error. Para confirmar qué conjuntos de herramientas acepta un modelo, consulte la sección Capacidades y características de la tarjeta del modelo del modelo.

Anthropic herramientas definidas

Anthropicproporciona un conjunto de herramientas predefinidas que Claude los modelos pueden utilizar para interactuar con los ordenadores. Al especificar una herramienta Anthropic definida, los tool_schema campos description y no son necesarios ni están permitidos. El modelo no ejecuta estas herramientas automáticamente; debe ejecutar cada acción solicitada y devolver un tool_result aClaude. Para saber cuáles de estas herramientas acepta cada modelo, consulte la tabla de capacidades y características del modeloModelos de un vistazo; si envía un tipo de herramienta que no admite un modelo, se obtiene un400 invalid_request_error.

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

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

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

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

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

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

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

El type campo identifica la herramienta y sus parámetros con fines de validación; el name campo 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 name campo debe ser único en la lista de herramientas; no se puede definir una herramienta con la name misma herramienta que una herramienta Anthropic definida en la misma llamada a la API.

Borrado automático de llamadas a herramientas (beta)

La compensación automática de llamadas con herramientas es una capacidad 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 acerca el límite de fichas, lo que permite gestionar el contexto de forma más eficiente en situaciones 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. Esta herramienta le proporciona una forma de administrar la memoria de las conversaciones. Con esta función, puede permitir que Claude recupere información fuera de la ventana de contexto al proporcionarle acceso a un directorio local. Esta función está disponible en versión beta. Para usar esta función, debe incluirla context-management-2025-06-27 en el anthropic_beta parámetro.

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 tener que cargar previamente todas sus definiciones en la ventana contextual. 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 incluirla tool-search-tool-2025-10-19 en el anthropic_beta parámetro. Tenga en cuenta que, por el momento, esta función solo está disponible a través de las InvokeModelWithResponseStream API InvokeModel y.

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 transmisión

# 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 mostrar un resultado que contenga bloques de tool_reference contenido que apunten a las herramientas que deseas Claude usar.

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

{
    "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

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

Ejemplo de solicitud con 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 (llamar 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"
}

Customer-provided resultado de la herramienta

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"
            }]
        }
    }]
}

Claudees el seguimiento (utilizando 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 del uso de las herramientas. Puedes proporcionar ejemplos como llamadas a funciones completas, formateadas exactamente igual que las salidas de LLM reales, sin necesidad de traducirlos a otro formato. Para usar esta función, debe incluirla tool-examples-2025-10-29 en el anthropic_beta parámetro.

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"
}

Mid-conversation cambios en las herramientas (Beta)

Claude Opus 5 permite añadir y eliminar herramientas en mitad de una conversación tool_addition y bloquear el tool_removal contenido de los role: "system" mensajes, en lugar de volver a enviar toda la tools matriz de nivel superior (lo que invalidaría la caché de mensajes).

Forma de solicitud

tool_additiony tool_removal los bloques aparecen en la content matriz de un role: "system" mensaje, junto con text los bloques opcionales. Cada bloque hace referencia a una herramienta a través de su tool campo. Se permiten varios bloques y se procesan en orden de contenido.

{
  "role": "system",
  "content": [
    {"type": "tool_removal", "tool": {"type": "tool_reference", "name": "get_weather"}},
    {"type": "tool_addition", "tool": {"type": "tool_reference", "name": "search_docs"}},
    {"type": "text", "text": "Tool set updated for phase 2."}
  ]
}

Ambos tipos de bloques admiten cache_control el almacenamiento rápido en caché.

Variantes de referencia de herramientas

El tool campo es una unión discriminada entype:

tool_referenceno acepta el {server}_{name} formulario redactado asignado a MCP-resolved las herramientas; para ello, utilice una de las variantes del MCP.

Semántica

Respuestas de error (400 invalid_request_error)

Uso forzoso de la herramienta

Claude Fable 5.1 y Claude Mythos 5.1 no admiten el uso forzoso de herramientas. Una solicitud que establece tool_choice {"type": "any"} o {"type": "tool", "name": "..."} devuelve un: 400 invalid_request_error

tool_choice: type "tool" and "any" are not supported for this model.

Esto se aplica a las CountTokens operaciones InvokeModelInvokeModelWithResponseStream, y. Los tool_choice valores predeterminados {"type": "auto"} y no {"type": "none"} se ven afectados y funcionan igual que antes. En la API de Converse, la toolChoice configuración equivalente (toolyany) muestra el mismo error.