Saltar al contenido principal

Uso de herramientas / Llamada a funciones

Intermedio

El uso de herramientas permite a Claude llamar a funciones que tú defines —búsqueda, una calculadora, tu base de datos, cualquier API— y usar los resultados. Es la base de todo agente.

What you'll learn
  • Cómo funciona el bucle agéntico de cuatro pasos, desde las definiciones de herramientas hasta la respuesta final
  • Cómo definir una herramienta en Python con nombre, descripción y entrada en JSON-Schema
  • Por qué las descripciones de las herramientas actúan como prompts que determinan cuándo y cómo las llama Claude
  • Cómo validar las entradas, devolver los errores como resultados y usar herramientas del lado del servidor de forma segura

El bucle​

El uso de herramientas es una conversación, no una única llamada. Le entregas a Claude un menú de herramientas; Claude elige una y se detiene; tú la ejecutas e informas de vuelta; Claude incorpora el resultado a su respuesta, repitiéndolo según sea necesario.

Guided walkthrough1 of 4
  1. Incluyes una lista de definiciones de herramientas, cada una con un nombre, una descripción y una entrada en JSON-Schema.

Definir una herramienta (Python)​

Una definición de herramienta no es más que un nombre, una descripción en lenguaje sencillo y un JSON-Schema para la entrada. Pásala en tools y luego comprueba stop_reason para saber cuándo Claude quiere actuar.

Herramienta get_weather + primera llamada

tools = [{
  "name": "get_weather",
  "description": "Get current weather for a city.",
  "input_schema": {
      "type": "object",
      "properties": {"city": {"type": "string"}},
      "required": ["city"],
  },
}]

msg = client.messages.create(
  model="claude-sonnet-5", max_tokens=1024,
  tools=tools,
  messages=[{"role": "user", "content": "What's the weather in Rome?"}],
)
# If msg.stop_reason == "tool_use": run the tool, then send a tool_result back.

Consejos​

Las pequeñas decisiones sobre cómo defines y gestionas las herramientas marcan una gran diferencia en la fiabilidad.

  • Las descripciones son prompts. Una description clara de la herramienta y la documentación de los parámetros mejoran enormemente cuándo/cómo la llama Claude.
  • Valida las entradas que recibes antes de ejecutarlas: nunca confíes en ellas a ciegas.
  • Devuelve los errores como resultados. Si una herramienta falla, envía un tool_result que describa el error para que Claude pueda recuperarse.
  • Herramientas del lado del servidor. Anthropic también ofrece herramientas integradas (p. ej., búsqueda web, ejecución de código, uso del ordenador): consulta la documentación para ver el menú actual.

:::warning Herramientas = acciones = riesgo Una herramienta que ejecuta acciones reales hereda un modelo de seguridad. Aplica el mínimo privilegio y mantén a una persona en el bucle para las llamadas arriesgadas: consulta Proteger agentes y herramientas. :::

Vocabulario del uso de herramientas
Pulsa Intro o Espacio para girar la tarjeta. Usa las flechas izquierda y derecha para moverte entre las tarjetas.Término mostrado.
1 / 4

Comprueba tus conocimientos

0/3
  1. Después de que Claude devuelva un bloque tool_use, ¿quién ejecuta la herramienta?
  2. Una herramienta que definiste falla en tiempo de ejecución. ¿Cuál es la acción recomendada?
  3. ¿Por qué importa tanto una descripción clara de la herramienta?
Key takeaways
  • El uso de herramientas es un bucle: envías las definiciones de herramientas, Claude devuelve un bloque tool_use y se detiene, tú la ejecutas y devuelves un tool_result, y Claude continúa hasta que responde.
  • Una definición de herramienta es un nombre, una descripción y una entrada en JSON-Schema: pásala en tools y comprueba stop_reason == tool_use.
  • Las descripciones son prompts; valida las entradas antes de ejecutarlas; devuelve los fallos como errores tool_result para que Claude pueda recuperarse.
  • Anthropic también ofrece herramientas del lado del servidor, y cualquier herramienta que ejecute acciones reales necesita el mínimo privilegio más una persona en el bucle.

Siguiente​