Transferts : Orchestration de plusieurs agents
Pe această pagină
Transferts : Orchestration de plusieurs agents
Un agent unique ne peut pas tout faire. Plus vous accumulez de domaines dans un seul jeu d’instructions, plus les directives se contredisent et plus les réponses deviennent fades. Les transferts permettent à un agent de déléguer la conversation à un autre agent spécialisé. C’est le mécanisme clé pour construire des systèmes multi-agents où chaque agent excelle dans son propre domaine.
Le concept de transfert
Un transfert est un passage de contrôle d’un agent à un autre. Lorsque l’agent A transfère à l’agent B, l’agent B prend le relais et génère la réponse. Le Runner gère cette transition automatiquement : vous n’avez pas à écrire de logique de routage explicite ni à appeler manuellement le second agent. Dans l’exemple ci-dessous, l’agent de triage reçoit une réclamation concernant le montant d’une facture, identifie le domaine et passe la main. Le client, quant à lui, ne voit qu’une conversation continue.
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)
Personnalisation de la description du transfert
Par défaut, un transfert utilise le nom et les instructions de l’agent cible. Cela fonctionne tant que les noms sont descriptifs, mais devient risqué lorsque deux agents se ressemblent. Dans ces cas-là, vous pouvez personnaliser la description pour guider le routage en listant les scénarios spécifiques qui doivent déclencher chaque transfert.
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.",
),
],
)
Transferts avec contexte
Un transfert n’est utile que si l’agent qui prend le relais sait ce qui se passe. Lorsqu’un agent effectue un transfert, l’historique de la conversation est transmis à l’agent cible : le nouvel agent a accès à tout ce qui a été dit jusqu’à présent, donc le client n’a pas à répéter son problème. En plus de cela, le contexte typé transporte des données de session structurées — ID client, abonnement souscrit, anciens tickets — et reste accessible aux outils de l’agent entrant.
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,
)
Modèle : Triage à trois niveaux
Les transferts ne se limitent pas au routage horizontal. Ils reproduisent également la structure d’escalade d’un véritable service de support. Voici un modèle de production à trois niveaux : le niveau L1 gère les demandes courantes, transfère les problèmes de configuration avancée au niveau L2, et le niveau L2 escalade les sujets d’architecture au niveau L3. Notez que le niveau 3 s’appuie sur un modèle plus performant, car il ne voit que les cas déjà filtrés par les deux niveaux précédents.
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",
)
Transferts bidirectionnels
La chaîne peut aussi être circulaire : deux agents peuvent se transférer le contrôle l’un à l’autre. C’est typique lorsqu’un prospect pose une question technique lors d’une conversation commerciale, puis revient aux tarifs une fois rassuré.
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]
Méfiez-vous des boucles infinies : une garde-fou ou max_turns est recommandé. Sans cette limite, une demande ambiguë peut faire rebondir la conversation d’un agent à l’autre jusqu’à épuisement de votre quota.
Suivi des transferts
Enfin, vous devez savoir qui a réellement répondu — à la fois pour vérifier votre routage et pour vos statistiques de support. Le RunResult vous indique quel agent a finalement produit la réponse.
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
Prenez l’habitude de journaliser cette valeur : si un agent de triage garde le contrôle de demandes qu’il aurait dû transférer, la distribution de last_agent révélera le problème bien avant les retours clients.
Puncte cheie
- Les transferts vous permettent de déléguer la conversation à un agent spécialisé
- L’historique de la conversation est transmis à l’agent cible
- Utilisez
Handoff(agent=..., description=...)pour guider le routage - Le contexte partagé (
RunContextWrapper) est accessible à tous les agents result.last_agent.nameindique quel agent a finalement répondu- Protégez les transferts bidirectionnels avec
max_turnspour éviter les boucles