Definición de herramientas para su agente
Creará herramientas personalizadas con el decorador @tool, escribirá descripciones claras que el LLM usará para decidir cuándo llamar a cada herramienta y añadirá validación de entradas con Pydantic.
Definición de herramientas para su agente es una lección gratuita de AI Engineering Academy en CoddyKit. Esta es la lección 2 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de AI Engineering Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de AI Engineering Academy incluye 4 lecciones en total.
Las herramientas dotan de superpoderes a los agentes
Un agente sin herramientas solo puede razonar sobre lo que ya sabe: no puede buscar en la web, consultar una base de datos ni enviar un correo electrónico. Las herramientas son funciones de Python que amplían las capacidades del agente, ya que le permiten realizar acciones en el mundo real y obtener información actualizada. Definir las herramientas con claridad es uno de los pasos más importantes para crear un agente fiable.
El decorador @tool en LangChain
El decorador @tool de LangChain transforma cualquier función de Python en una herramienta que el agente puede invocar. El docstring de la función se convierte en la descripción de la herramienta que utiliza el LLM para decidir cuándo invocarla. Una descripción clara y específica mejora considerablemente la precisión del agente al seleccionar herramientas.
from langchain_core.tools import tool
@tool
def get_weather(city: str) -> str:
'''Get the current weather conditions for a given city.
Use this tool when the user asks about weather in a specific location.
Input should be just the city name, e.g. 'London' or 'New York'.
'''
# Real implementation would call a weather API
return f'The weather in {city} is 18 degrees Celsius and partly cloudy.'
print(get_weather.name) # 'get_weather'
print(get_weather.description) # The docstring aboveAnotaciones de tipos y generación de esquemas
LangChain genera automáticamente un esquema JSON para cada herramienta a partir de las anotaciones de tipos de Python. El agente recibe este esquema en el prompt del sistema, por lo que sabe qué argumentos son obligatorios, qué tipos tienen y qué restricciones se aplican. Anote siempre las funciones de sus herramientas con tipos precisos.
from langchain_core.tools import tool
@tool
def calculate_compound_interest(
principal: float,
annual_rate: float,
years: int
) -> float:
'''Calculate compound interest earned over a number of years.
Args:
principal: Initial investment amount in dollars.
annual_rate: Annual interest rate as a decimal (e.g. 0.05 for 5%).
years: Number of years to compound.
Returns:
Final amount after compounding.
'''
return principal * (1 + annual_rate) ** years
# Inspect the auto-generated schema
print(calculate_compound_interest.args_schema.schema())Validación de entradas con Pydantic
Para herramientas con entradas complejas, defina un modelo de Pydantic como args_schema. Esto le proporciona validación automática, conversión de tipos y documentación descriptiva a nivel de campo que el LLM puede consultar al decidir cómo invocar la herramienta.
from langchain_core.tools import tool
from pydantic import BaseModel, Field
class SearchInput(BaseModel):
query: str = Field(description='The search query to look up.')
num_results: int = Field(default=5, ge=1, le=20, description='Number of results to return (1-20).')
@tool(args_schema=SearchInput)
def web_search(query: str, num_results: int = 5) -> str:
'''Search the web for current information on any topic.
Use this for facts that may have changed after the model training cutoff.
'''
return f'Searching for "{query}", returning {num_results} results...'Escribir descripciones eficaces para las herramientas
La descripción de la herramienta es la parte más importante de su definición: el LLM la lee para decidir cuándo y cómo invocarla. Una buena descripción responde a estas preguntas: ¿Qué hace esta herramienta? ¿Cuándo debe utilizarse? ¿Cómo debe ser la entrada? ¿Cuál será la salida?
- Incorrecto: «Herramienta de búsqueda».
- Correcto: «Buscar en la web noticias, hechos o datos actuales. Utilizar cuando el usuario pregunte por acontecimientos recientes o hechos que no estén en los datos de entrenamiento. Entrada: una consulta de búsqueda concisa».
Tipos de retorno de las herramientas
Las herramientas pueden devolver cadenas, diccionarios u objetos Pydantic estructurados. Sin embargo, el agente necesita finalmente el resultado como texto para incluirlo en la conversación. Si devuelve un diccionario, LangChain lo serializa como una cadena. Para datos anidados complejos, dé formato al resultado como un resumen legible en lugar de usar JSON sin procesar; así ayudará al modelo a razonar sobre ellos.
from langchain_core.tools import tool
import json
@tool
def get_stock_price(ticker: str) -> str:
'''Look up the current stock price for a given ticker symbol.
Input should be the stock ticker symbol in uppercase, e.g. AAPL or MSFT.
'''
# Stub — real implementation calls a financial API
data = {'ticker': ticker, 'price': 182.50, 'currency': 'USD', 'change': '+1.2%'}
return f'{ticker}: ${data["price"]} ({data["change"]})'Gestionar los errores de las herramientas correctamente
Las herramientas fallan. Las API dejan de funcionar, se producen tiempos de espera de red y los usuarios proporcionan entradas no válidas. En lugar de permitir que las excepciones detengan el ciclo del agente, envuelva la lógica de la herramienta en un bloque try/except y devuelva una cadena de error descriptiva. De este modo, el agente puede razonar sobre el fallo y decidir si debe reintentar o utilizar otro enfoque.
from langchain_core.tools import tool
import requests
@tool
def fetch_url(url: str) -> str:
'''Fetch the text content of a web page given its URL.
Use for accessing specific documents or web pages the user references.
'''
try:
resp = requests.get(url, timeout=10)
resp.raise_for_status()
return resp.text[:2000] # Return first 2000 chars
except requests.Timeout:
return 'Error: Request timed out after 10 seconds.'
except requests.HTTPError as e:
return f'Error: HTTP {e.response.status_code}'
except Exception as e:
return f'Error fetching URL: {str(e)}'Herramientas asíncronas
Cuando su agente ejecuta muchas llamadas a herramientas o las herramientas realizan solicitudes de red limitadas por E/S, defina funciones de herramientas asíncronas para evitar bloquear el bucle de eventos. El ejecutor de agentes de LangChain admite herramientas asíncronas de forma nativa: solo tiene que usar async def en la función de su herramienta.
from langchain_core.tools import tool
import httpx
@tool
async def async_fetch(url: str) -> str:
'''Asynchronously fetch content from a URL.
Preferred over fetch_url when making multiple concurrent requests.
'''
async with httpx.AsyncClient(timeout=10) as client:
try:
resp = await client.get(url)
resp.raise_for_status()
return resp.text[:2000]
except Exception as e:
return f'Error: {str(e)}'Organizar herramientas en un toolkit
Cuando tenga muchas herramientas relacionadas, agrúpelas en un toolkit: una clase que devuelve una lista de herramientas. Los toolkits de LangChain siguen un patrón común: aceptan configuración, como claves de API, en el constructor y exponen un método get_tools(). Esto permite gestionar las herramientas de forma ordenada y reutilizable entre distintos agentes.
from langchain_core.tools import BaseTool
from typing import List
class WeatherToolkit:
def __init__(self, api_key: str):
self.api_key = api_key
def get_tools(self) -> List[BaseTool]:
return [
get_weather, # defined earlier with @tool
get_weather_forecast, # another tool
get_weather_alert # another tool
]
# Usage
toolkit = WeatherToolkit(api_key='your_weather_api_key')
tools = toolkit.get_tools()
print(f'Loaded {len(tools)} weather tools')Limitar el acceso a las herramientas según el rol del usuario
No todos los usuarios deberían tener acceso a todas las herramientas. Un usuario con permisos de solo lectura no debería activar una herramienta send_email ni delete_record. Implemente el acceso a las herramientas basado en roles seleccionando qué herramientas pasar al agente según los permisos del usuario autenticado.
def get_tools_for_user(user_role: str) -> list:
read_tools = [web_search, get_weather, calculate_compound_interest]
write_tools = [send_email, create_calendar_event, update_record]
if user_role == 'admin':
return read_tools + write_tools
elif user_role == 'member':
return read_tools
else:
return [web_search] # Guest: only public searchBuenas prácticas para documentar herramientas
Las herramientas bien documentadas reducen considerablemente los errores del agente. Siga estas prácticas recomendadas: use un nombre claro que empiece por un verbo (search_web, no websearch), describa explícitamente el formato de entrada esperado, indique cuándo NO se debe usar la herramienta para evitar falsos positivos y describa el aspecto de la salida para que el modelo pueda interpretarla correctamente.
Comprobación rápida
Compruebe su comprensión de la definición de herramientas para agentes de LangChain.
Recapitulación de la lección
En esta lección aprendió que: el decorador @tool convierte las funciones de Python en herramientas que el agente puede invocar y usa sus docstrings como descripciones, los esquemas de Pydantic añaden entradas tipadas y validadas y las herramientas deben gestionar los errores correctamente devolviendo cadenas de error descriptivas. A continuación ensamblaremos un agente ReAct completo con LangChain y trazaremos sus pasos de razonamiento.
Aprende Python con un tutor de IA — gratis
Escribe y ejecuta código real en tu navegador, obtén ayuda instantánea de un tutor de IA disponible 24/7 y continúa donde lo dejaste en la web o en la aplicación.
- Cursos
- 30
- Lecciones
- 120
Preguntas frecuentes
¿La lección «Definición de herramientas para su agente» es gratis?
Sí — el texto completo de «Definición de herramientas para su agente» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de AI Engineering Academy, actualiza a CoddyKit PRO. El curso de AI Engineering Academy incluye 4 lecciones en total.
¿Qué aprenderé en «Definición de herramientas para su agente»?
Creará herramientas personalizadas con el decorador @tool, escribirá descripciones claras que el LLM usará para decidir cuándo llamar a cada herramienta y añadirá validación de entradas con Pydantic. Practicas AI Engineering Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.
¿Necesito experiencia previa para empezar AI Engineering Academy?
No se requiere experiencia previa. AI Engineering Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 2 de 4.
¿Cuánto tiempo toma la lección «Definición de herramientas para su agente»?
La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.
¿Puedo escribir y ejecutar código en esta lección de AI Engineering Academy?
Sí. Cada lección de AI Engineering Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.
Todas las lecciones de este curso
- El framework ReAct: pensar, actuar y observar
- Definición de herramientas para su agente
- Creación de un agente ReAct con LangChain
- Gestión de fallos y bucles de los agentes