Búsqueda de herramientas: herramientas dinámicas
En esta página
Búsqueda de herramientas: herramientas dinámicas
Un agente de demostración funciona perfectamente con tres o cuatro herramientas. Sin embargo, un agente empresarial acumula inevitablemente decenas, a veces cientos: facturación, RR. HH., CRM, documentos, programación. A esa escala, enviar el catálogo completo al modelo en cada solicitud resulta ineficiente y costoso en términos de tokens. La búsqueda de herramientas resuelve este problema seleccionando dinámicamente las herramientas relevantes para cada solicitud.
El problema de tener demasiadas herramientas
Imagina un agente con 50 herramientas. En cada llamada a la API, los esquemas de las 50 herramientas se envían en el prompt. Esto consume miles de tokens y puede confundir al modelo: cuanto más larga es la lista, más similares se vuelven las descripciones y más duda el modelo entre herramientas vecinas. Los costes aumentan mientras la precisión disminuye; la peor combinación posible.
# Problema: demasiadas herramientas
agent = Agent(
name="Super Agent",
instructions="You can do anything.",
tools=[tool_1, tool_2, tool_3, ... , tool_50], # 50 tools = lots of tokens
)
Activación de la búsqueda de herramientas
La búsqueda de herramientas utiliza un índice semántico para seleccionar las herramientas relevantes basándose en la solicitud. Declaras tus herramientas como de costumbre, pero el parámetro tool_use_behavior="auto" permite que el modelo elija del catálogo en lugar de cargarlo todo de antemano. En el ejemplo siguiente, una solicitud para enviar un recordatorio de pago no activará las herramientas de RR. HH., y viceversa.
from agents import Agent, Runner, function_tool
# Definir muchas herramientas
@function_tool
def create_invoice(client: str, amount: float) -> str:
"""Creates an invoice for a client."""
return f"Invoice created for {client}: €{amount}"
@function_tool
def send_reminder(invoice_id: str) -> str:
"""Sends a payment reminder for an unpaid invoice."""
return f"Reminder sent for invoice {invoice_id}"
@function_tool
def generate_hr_report(month: str) -> str:
"""Generates a human resources report for a given month."""
return f"HR report generated for {month}"
@function_tool
def schedule_interview(candidate: str, date: str) -> str:
"""Schedules a job interview with a candidate."""
return f"Interview scheduled with {candidate} on {date}"
# Muchas otras herramientas...
agent = Agent(
name="Enterprise Agent",
instructions="You manage company operations.",
tools=[
create_invoice,
send_reminder,
generate_hr_report,
schedule_interview,
# ... 50 other tools
],
tool_use_behavior="auto", # The model selects dynamically
)
Patrón: selección manual de herramientas
Si deseas tener el control total sobre la selección de herramientas, implementa tu propia lógica. El principio es sencillo: un agente enrutador pequeño lee la solicitud y simplemente nombra el dominio relevante. A continuación, construyes el agente especializado al vuelo con solo las herramientas de ese dominio. Una frase como «enviar un recordatorio para la factura F-2026-114» sale del enrutador con la respuesta accounting, y el agente de ejecución nunca ve las herramientas de RR. HH.
from agents import Agent, Runner, function_tool
# Agrupar herramientas por dominio
accounting_tools = [create_invoice, send_reminder]
hr_tools = [generate_hr_report, schedule_interview]
# Un agente enrutador que selecciona el dominio
router = Agent(
name="Router",
instructions="""Determine the domain of the request.
Respond only with 'accounting' or 'hr'.""",
model="gpt-5.6-terra", # Fast and cheap for routing
output_type=str,
)
async def handle_request(message: str):
# Paso 1: Determinar el dominio
route = await Runner.run(router, message)
domain = route.final_output.strip().lower()
# Paso 2: Crear el agente especializado con las herramientas correctas
if domain == "accounting":
tools = accounting_tools
instructions = "You manage the company's accounting."
elif domain == "hr":
tools = hr_tools
instructions = "You manage human resources."
else:
tools = accounting_tools + hr_tools
instructions = "You manage company operations."
specialized_agent = Agent(
name=f"{domain.capitalize()} Agent",
instructions=instructions,
tools=tools,
model="gpt-5.6-terra",
)
result = await Runner.run(specialized_agent, message)
return result.final_output
El uso de gpt-5.6-terra tanto para el enrutamiento como para la ejecución pertenece a la generación anterior de modelos; el razonamiento detrás del patrón permanece idéntico con la familia GPT-5.6, donde los ajustes de esfuerzo distinguen al enrutador rápido del ejecutor.
Patrón: herramientas dinámicas conscientes del contexto
La selección no depende solo de la pregunta formulada; también depende de quién la hace. Puedes adaptar las herramientas disponibles basándote en el usuario conectado, matando dos pájaros de un tiro: se envían menos tokens y, lo que es más importante, se hacen cumplir los controles de acceso antes de que el modelo siquiera razone. Un empleado de ventas recibe herramientas de presupuestación, pero delete_account simplemente no existe en su agente.
from dataclasses import dataclass
@dataclass
class UserContext:
role: str # "admin", "manager", "employee"
department: str
def get_tools_for_role(ctx: UserContext) -> list:
"""Returns authorized tools based on role."""
base_tools = [search_document, view_schedule]
if ctx.role in ("admin", "manager"):
base_tools.extend([create_invoice, generate_hr_report])
if ctx.role == "admin":
base_tools.extend([modify_permissions, delete_account])
if ctx.department == "sales":
base_tools.extend([search_client, create_quote])
return base_tools
async def create_agent_for_user(ctx: UserContext):
tools = get_tools_for_role(ctx)
return Agent(
name="Custom Agent",
instructions=f"You assist a {ctx.role} in the {ctx.department} department.",
tools=tools,
model="gpt-5.6-terra",
)
Optimización de las descripciones de las herramientas
Sea cual sea el mecanismo de selección que elijas, este depende de un único material: el texto de tus descripciones. La calidad de estas descripciones impacta directamente en la relevancia de la selección. Compara las dos declaraciones siguientes: la primera no dice nada sobre el escenario de uso, mientras que la segunda nombra las entradas, la salida y cuándo utilizarla.
# Malo: descripción vaga
@function_tool
def process_data(data: str) -> str:
"""Processes data."""
return "OK"
# Bueno: descripción precisa y contextualizada
@function_tool
def calculate_gross_margin(revenue: float, production_cost: float) -> str:
"""Calculates gross margin as a percentage from revenue
and production cost. Useful for quarterly financial analysis."""
margin = ((revenue - production_cost) / revenue) * 100
return f"Gross margin: {margin:.1f}% (Revenue: €{revenue}, Costs: €{production_cost})"
Una buena descripción de herramienta es como un buen docstring: explica cuándo usar la herramienta, no solo qué hace. Dedica diez minutos a revisar las descripciones de tu agente, preguntándote por cada una si un compañero podría elegir la herramienta correcta leyendo solo esa frase. Ese es exactamente el ejercicio que realiza el modelo.
Puntos clave
- La búsqueda de herramientas selecciona dinámicamente las herramientas relevantes para cada solicitud
- Con muchas herramientas, un agente enrutador puede determinar el dominio de antemano
- Adapta las herramientas disponibles basándote en el rol y el contexto del usuario
- La calidad de la descripción de la herramienta impacta en la precisión de la selección
- Usa un modelo ligero para un enrutamiento rápido y un modelo capaz para la ejecución