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

Transferencias: orquestación de varios agentes

Lección 12 de 25 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Transferencias: orquestación de varios agentes
  2. El concepto de transferencia
  3. Personalización de la descripción de la transferencia
  4. Transferencias con contexto
  5. Patrón: triaje de tres niveles
  6. Transferencias bidireccionales
  7. Seguimiento de las transferencias
  8. Puntos clave

Transferencias: orquestación de varios agentes

Un único agente no puede hacerlo todo. Cuantos más dominios acumules en un mismo conjunto de instrucciones, más se contradecirán las directrices y más tibias serán las respuestas. Las transferencias permiten que un agente delegue la conversación en otro agente especializado. Este es el mecanismo clave para construir sistemas multiagente donde cada agente destaca en su propio dominio.

El concepto de transferencia

Una transferencia es un traspaso de control de un agente a otro. Cuando el Agente A transfiere al Agente B, este último toma el relevo y genera la respuesta. El Runner gestiona esta transición automáticamente: no tienes que escribir lógica de enrutamiento explícita ni llamar manualmente al segundo agente. En el ejemplo siguiente, el agente de triaje recibe una reclamación sobre el importe de una factura, identifica el dominio y pasa el testigo. El cliente, mientras tanto, solo ve una conversación continua.

from agents import Agent, Runner

billing_agent = Agent(
    name="Billing Agent",
    instructions="""You handle billing questions: invoices, payments,
    refunds, subscriptions. Respond precisely and professionally.""",
    model="gpt-5.6-terra",
)

technical_agent = Agent(
    name="Technical Agent",
    instructions="""You handle technical support: bugs, configuration,
    installation, troubleshooting. Provide step-by-step instructions.""",
    model="gpt-5.6-terra",
)

triage_agent = Agent(
    name="Triage Agent",
    instructions="""You are the first point of contact.
    Analyze the customer's request and transfer it to the appropriate agent.
    - Billing questions → Billing Agent
    - Technical questions → Technical Agent""",
    handoffs=[billing_agent, technical_agent],
    model="gpt-5.6-terra",
)

result = Runner.run_sync(
    triage_agent,
    "My latest invoice seems incorrect; the amount is too high."
)
# The triage agent hands off to the billing agent
print(f"Answered by: {result.last_agent.name}")
print(result.final_output)

Personalización de la descripción de la transferencia

Por defecto, una transferencia utiliza el nombre y las instrucciones del agente de destino. Esto funciona bien siempre que los nombres sean descriptivos, pero se vuelve arriesgado cuando dos agentes se parecen. En esos casos, puedes personalizar la descripción para guiar el enrutamiento enumerando los escenarios específicos que deben desencadenar cada transferencia.

from agents import Handoff

triage_agent = Agent(
    name="Triage Agent",
    instructions="Transfer the request to the specialized agent.",
    handoffs=[
        Handoff(
            agent=billing_agent,
            description="Transfer for payment questions, invoices, refunds, and subscriptions.",
        ),
        Handoff(
            agent=technical_agent,
            description="Transfer for technical issues, bugs, and configuration help requests.",
        ),
    ],
)

Transferencias con contexto

Una transferencia solo es útil si el agente que toma el relevo sabe qué está ocurriendo. Cuando un agente realiza una transferencia, el historial de la conversación se pasa al agente de destino: el nuevo agente tiene acceso a todo lo dicho hasta ese momento, por lo que el cliente no tiene que repetir su problema. Además, el contexto tipado transporta datos estructurados de la sesión (ID de cliente, plan suscrito, tickets anteriores) y permanece accesible para las herramientas del agente entrante.

from dataclasses import dataclass
from agents import Agent, Runner, RunContextWrapper, function_tool

@dataclass
class CustomerContext:
    client_id: str
    plan: str
    ticket_history: list[str]

@function_tool
def view_invoice(ctx: RunContextWrapper[CustomerContext], month: str) -> str:
    """Views the invoice for a given month for the current customer."""
    client_id = ctx.context.client_id
    return f"Invoice for {month} for {client_id}: €149.99 (plan {ctx.context.plan})"

billing_agent = Agent(
    name="Billing Agent",
    instructions="You handle billing. Use the customer context.",
    tools=[view_invoice],
    model="gpt-5.6-terra",
)

triage_agent = Agent(
    name="Triage",
    instructions="Transfer to the right agent.",
    handoffs=[billing_agent],
    model="gpt-5.6-terra",
)

context = CustomerContext(
    client_id="cli_456",
    plan="Pro",
    ticket_history=["Ticket #001: Slow connection"]
)

result = Runner.run_sync(
    triage_agent,
    "Can you check my invoice for March?",
    context=context,
)

Patrón: triaje de tres niveles

Las transferencias no se limitan al enrutamiento horizontal. También replican la estructura de escalado de un servicio de asistencia real. Aquí tienes un patrón de producción con tres niveles: L1 gestiona consultas rutinarias, transfiere problemas de configuración avanzada a L2, y L2 escala temas de arquitectura a L3. Ten en cuenta que el nivel 3 depende de un modelo más capaz, ya que solo ve casos que ya han sido filtrados por los dos niveles anteriores.

level3_agent = Agent(
    name="L3 Technical Expert",
    instructions="""You are a level 3 technical expert.
    You handle complex architecture and infrastructure problems.
    If you cannot resolve the issue, indicate that human escalation is necessary.""",
    model="gpt-5.6-sol",  # The most capable model for complex cases
)

level2_agent = Agent(
    name="L2 Technical Support",
    instructions="""You are a level 2 technician.
    You handle advanced configuration problems.
    If the problem is too complex, transfer to level 3.""",
    handoffs=[level3_agent],
    model="gpt-5.6-terra",
)

level1_agent = Agent(
    name="L1 Customer Support",
    instructions="""You are the first point of contact for customer support.
    Handle simple questions (password, account, navigation).
    Transfer technical problems to level 2.""",
    handoffs=[level2_agent],
    model="gpt-5.6-terra",
)

Transferencias bidireccionales

La cadena también puede ser circular: dos agentes pueden transferirse el control mutuamente. Esto es típico cuando un posible cliente formula una pregunta técnica durante una conversación de ventas y luego vuelve a los precios una vez reassurado.

sales_agent = Agent(
    name="Sales Agent",
    instructions="""You sell products. If the customer asks
    for technical support, transfer to the technical agent.""",
)

support_agent = Agent(
    name="Support Agent",
    instructions="""You provide technical support. If the customer
    wants to buy something, transfer to the sales agent.""",
)

# Bidirectional handoffs
sales_agent.handoffs = [support_agent]
support_agent.handoffs = [sales_agent]

Vigila los bucles infinitos: se recomienda una barrera de seguridad o max_turns. Sin este límite, una solicitud ambigua puede hacer rebotar la conversación de un agente a otro hasta agotar tu cuota.

Seguimiento de las transferencias

Por último, necesitas saber quién ha respondido realmente, tanto para verificar tu enrutamiento como para tus estadísticas de soporte. El RunResult te indica qué agente ha producido finalmente la respuesta.

result = Runner.run_sync(triage_agent, "I have a critical bug")

print(f"Initial agent: triage_agent")
print(f"Final agent: {result.last_agent.name}")
# Prints "Technical Agent" if triage worked correctly

Acostúmbrate a registrar este valor: si un agente de triaje mantiene el control de solicitudes que debería haber transferido, la distribución de last_agent revelará el problema mucho antes que los comentarios de los clientes.

Puntos clave

  • Las transferencias te permiten delegar la conversación en un agente especializado
  • El historial de la conversación se pasa al agente de destino
  • Usa Handoff(agent=..., description=...) para guiar el enrutamiento
  • El contexto compartido (RunContextWrapper) es accesible para todos los agentes
  • result.last_agent.name indica qué agente ha respondido finalmente
  • Protege las transferencias bidireccionales con max_turns para evitar bucles