Transferencias: orquestación de varios agentes
En esta página
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.nameindica qué agente ha respondido finalmente- Protege las transferencias bidireccionales con
max_turnspara evitar bucles