Overdrachten: het orkestreren van meerdere agents
Op deze pagina
Overdrachten: het orkestreren van meerdere agents
Eén enkele agent kan niet alles aan. Hoe meer domeinen u in één set instructies propt, hoe meer de richtlijnen elkaar tegenspreken en hoe flauwer de reacties worden. Overdrachten stellen een agent in staat het gesprek over te dragen aan een andere gespecialiseerde agent. Dit is het kernmechanisme voor het bouwen van systemen met meerdere agents, waarbij elke agent uitblinkt in zijn eigen domein.
Het concept van overdracht
Een overdracht is een overdracht van controle van de ene agent naar de andere. Wanneer Agent A overdraagt aan Agent B, neemt Agent B het over en genereert het antwoord. De Runner regelt deze overgang automatisch: u schrijft geen expliciete routeringslogica en roept de tweede agent niet handmatig aan. In het onderstaande voorbeeld ontvangt de triage-agent een klacht over een factuurbedrag, herkent het domein en geeft het stokje door. De klant ziet ondertussen slechts één doorlopend gesprek.
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)
De beschrijving van de overdracht aanpassen
Standaard gebruikt een overdracht de naam en instructies van de doel-agent. Dit werkt prima zolang de namen beschrijvend zijn, maar wordt riskant wanneer twee agents op elkaar lijken. In die gevallen kunt u de beschrijving aanpassen om de routering te sturen door de specifieke scenario’s op te sommen die elke overdracht moeten activeren.
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.",
),
],
)
Overdrachten met context
Een overdracht is alleen nuttig als de agent die het overneemt weet wat er aan de hand is. Wanneer een agent een overdracht uitvoert, wordt de gespreksgeschiedenis doorgegeven aan de doel-agent: de nieuwe agent heeft toegang tot alles wat tot nu toe is gezegd, zodat de klant zijn probleem niet hoeft te herhalen. Daarbovenop draagt getypeerde context gestructureerde sessiegegevens met zich mee – klant-ID, geabonneerd pakket, eerdere tickets – en blijft deze toegankelijk voor de tools van de binnenkomende agent.
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,
)
Patroon: Drieniveau-triage
Overdrachten zijn niet beperkt tot horizontale routering. Ze repliceren ook de escalatiestructuur van een echte ondersteuningsdienst. Hier is een productiepatroon met drie niveaus: L1 behandelt routinematige vragen, draagt geavanceerde configuratieproblemen over aan L2, en L2 escaleert architectuuronderwerpen naar L3. Merk op dat niveau 3 vertrouwt op een bekwaam model, aangezien het alleen gevallen ziet die al zijn gefilterd door de twee voorgaande niveaus.
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",
)
Bidirectionele overdrachten
De keten kan ook circulair zijn: twee agents kunnen de controle heen en weer overdragen. Dit is typisch wanneer een prospect tijdens een verkoopgesprek een technische vraag stelt, en vervolgens terugkeert naar de prijsstelling zodra hij gerustgesteld is.
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]
Pas op voor oneindige lussen: een veiligheidsmechanisme of max_turns wordt aanbevolen. Zonder deze limiet kan een dubbelzinnig verzoek het gesprek van de ene agent naar de andere laten stuiteren totdat uw quotum is uitgeput.
Overdrachten traceren
Tot slot moet u weten wie daadwerkelijk heeft geantwoord – zowel om uw routering te verifiëren als voor uw ondersteuningsstatistieken. Het RunResult vertelt u welke agent uiteindelijk het antwoord heeft gegenereerd.
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
Maak er een gewoonte van om deze waarde te loggen: als een triage-agent de controle behoudt over verzoeken die hij had moeten overdragen, zal de verdeling van last_agent het probleem ruim vóór de klantfeedback aan het licht brengen.
Belangrijkste punten
- Met overdrachten kunt u het gesprek delegeren aan een gespecialiseerde agent
- De gespreksgeschiedenis wordt doorgegeven aan de doel-agent
- Gebruik
Handoff(agent=..., description=...)om de routering te sturen - Gedeelde context (
RunContextWrapper) is toegankelijk voor alle agents result.last_agent.namegeeft aan welke agent uiteindelijk heeft geantwoord- Bescherm bidirectionele overdrachten met
max_turnsom lussen te voorkomen