Ir al contenido principal
Español— Elegir un idioma
Menú

Búsqueda de herramientas: herramientas dinámicas

Lección 10 de 25 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Búsqueda de herramientas: herramientas dinámicas
  2. El problema de tener demasiadas herramientas
  3. Activación de la búsqueda de herramientas
  4. Patrón: selección manual de herramientas
  5. Patrón: herramientas dinámicas conscientes del contexto
  6. Optimización de las descripciones de las herramientas
  7. Puntos clave

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