Declarar herramientas en el SDK
En esta página
Declarar herramientas en el SDK
Las herramientas son las capacidades concretas de tu agente. Sin ellas, un agente solo puede generar texto; con herramientas, puede consultar bases de datos, llamar a APIs y enviar correos electrónicos. Sin embargo, debes declararlas correctamente, porque la calidad de una herramienta no depende solo de su código, sino también de lo bien que el modelo la entienda.
El decorador @function_tool
La forma más sencilla de crear una herramienta es el decorador @function_tool, que convierte una función estándar de Python en una capacidad que el agente puede invocar.
from agents import function_tool
@function_tool
def search_customer(email: str) -> str:
"""Busca un cliente por dirección de correo electrónico en la base de datos.
Args:
email: La dirección de correo electrónico del cliente a buscar.
"""
# En producción: llama a tu base de datos
customers = {
"[email protected]": {"name": "Alice Dupont", "plan": "Pro", "since": "2024"},
"[email protected]": {"name": "Bob Martin", "plan": "Starter", "since": "2025"},
}
customer = customers.get(email)
if customer:
return f"Cliente encontrado: {customer['name']}, plan {customer['plan']}, cliente desde {customer['since']}"
return f"No se ha encontrado ningún cliente con el correo {email}"
No se declara nada dos veces: el SDK utiliza el nombre de la función como nombre de la herramienta, la docstring como descripción y las pistas de tipo para generar el esquema JSON de los parámetros. En otras palabras, tu docstring ya no es solo un comentario para tus compañeros; es el texto que lee el modelo para decidir si debe llamar a esta función. Una docstring vaga provoca llamadas imprecisas.
Personalizar nombre y descripción
Cuando el nombre de tu función sigue convenciones internas en lugar de la lógica de negocio, puedes anular lo que ve el modelo.
@function_tool(
name_override="search_crm",
description_override="Busca un cliente en el CRM por correo, nombre o número de cuenta."
)
def search_customer(identifier: str) -> str:
"""Busca un cliente."""
# ...
return "Resultado"
Tipos de parámetros admitidos
Además de los tipos nativos de Python, el SDK acepta modelos de Pydantic. Cuando una herramienta recibe tres o más parámetros, agrúpalos: el esquema resulta más legible para el modelo y la validación te protege de valores atípicos.
from pydantic import BaseModel, Field
from typing import Optional
from agents import function_tool
class SearchFilter(BaseModel):
category: str = Field(description="Categoría del producto")
max_price: Optional[float] = Field(None, description="Precio máximo en euros")
in_stock: bool = Field(True, description="Solo productos en stock")
@function_tool
def search_products(filter: SearchFilter) -> str:
"""Busca productos según los criterios especificados."""
results = []
# Lógica de búsqueda usando filter.category, filter.max_price, etc.
return f"Se han encontrado {len(results)} productos en {filter.category}"
Los modelos de Pydantic validan automáticamente las entradas y proporcionan al modelo descripciones detalladas campo por campo.
Devolver resultados estructurados
Una herramienta devuelve siempre una cadena de texto. Cuando tus datos tienen estructura —múltiples métricas, una lista, tipos mixtos—, serialízalos como JSON en lugar de redactar una frase: el modelo leerá las claves con mucha más fiabilidad que el texto libre.
import json
from agents import function_tool
@function_tool
def get_sales_stats(month: str, year: int) -> str:
"""Recupera las estadísticas de ventas de un mes determinado."""
stats = {
"month": month,
"year": year,
"revenue": 145000,
"sales_count": 342,
"avg_basket": 423.98,
"top_products": ["Laptop Pro", "Tablet Air", "Monitor 4K"]
}
return json.dumps(stats, ensure_ascii=False, indent=2)
Herramientas alojadas por OpenAI
Además de tus funciones personalizadas, el SDK proporciona acceso a herramientas gestionadas por OpenAI que se ejecutan en el lado de la plataforma.
from agents import Agent, WebSearchTool, FileSearchTool, CodeInterpreterTool
agent = Agent(
name="Asistente de propósito general",
instructions="Eres un asistente capaz de buscar en la web, analizar archivos y ejecutar código.",
tools=[
WebSearchTool(),
FileSearchTool(
vector_store_ids=["vs_abc123"],
max_num_results=10,
),
CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
],
)
WebSearchTool permite al agente buscar en internet en tiempo real y no requiere configuración. FileSearchTool realiza búsquedas semánticas en tus archivos, pero asume una configuración previa: debes crear un almacén vectorial mediante la API de OpenAI y subir tus documentos a él; de ahí el vs_abc123 que se pasa como parámetro. CodeInterpreterTool permite al agente escribir y ejecutar código Python en un contenedor aislado, lo que lo convierte en la opción predilecta para el análisis de datos y la generación de gráficos. Requiere un tool_config que especifique este contenedor: {"type": "auto"} lo crea bajo demanda (el SDK openai-agents rechaza CodeInterpreterTool() sin él).
Combinar herramientas personalizadas y alojadas
La verdadera potencia reside en la combinación. Un analista financiero necesita tus datos internos, capacidades de cálculo y contexto de mercado: tres fuentes que ninguna herramienta única cubre.
agent = Agent(
name="Analista financiero",
instructions="""Eres un analista financiero.
Usa herramientas internas para recuperar datos,
el intérprete de código para analizarlos
y la búsqueda web para obtener contexto de mercado.""",
tools=[
get_sales_stats,
search_customer,
WebSearchTool(),
CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
],
)
Observa cómo las instrucciones especifican para qué sirve cada familia de herramientas. Sin esta claridad, un agente con cuatro herramientas duda, prueba dos innecesariamente y aumenta la latencia sin motivo.
Puntos clave
@function_toolconvierte una función de Python en una herramienta del agente- La docstring y las pistas de tipo generan automáticamente el esquema JSON
- Usa Pydantic para parámetros complejos con validación
- Las herramientas devuelven siempre cadenas (JSON si están estructuradas)
- Combina tus herramientas personalizadas con WebSearchTool, FileSearchTool y CodeInterpreterTool