Käsienluovutukset: Useiden agenttien orkestrointi
Tällä sivulla
Käsienluovutukset: Useiden agenttien orkestrointi
Yksi ainoa agentti ei pysty tekemään kaikkea. Mitä enemmän toimialueita ahdetaan yhteen ohjeistukseen, sitä enemmän ohjeet ovat ristiriidassa keskenään ja sitä vetämättömämmiksi vastaukset muuttuvat. Käsienluovutukset (handoffs) mahdollistavat sen, että agentti siirtää keskustelun toiselle erikoistuneelle agentille. Tämä on keskeinen mekanismi moniagenttijärjestelmien rakentamiseen, joissa jokainen agentti loistaa omalla toimialueellaan.
Käsienluovutuksen käsite
Käsienluovutus on vallan siirtoa yhdeltä agentilta toiselle. Kun Agentti A luovuttaa vuoron Agentti B:lle, Agentti B ottaa vastuun ja tuottaa vastauksen. Runner hoitaa tämän siirtymän automaattisesti: sinun ei tarvitse kirjoittaa eksplisiittistä reitityslogiikkaa tai kutsua toista agenttia manuaalisesti. Alla olevassa esimerkissä lajitteluagentti (triage agent) vastaanottaa valituksen laskun summasta, tunnistaa aihealueen ja ojentaa viestin eteenpäin. Asiakas näkee meanwhile vain yhden jatkuvan keskustelun.
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)
Käsienluovutuskuvauksen mukauttaminen
Oletusarvoisesti käsienluovutus käyttää kohdeagentin nimeä ja ohjeistusta. Tämä toimii hyvin, kunhan nimet ovat kuvaavia, mutta muuttuu riskialttiiksi, kun kaksi agenttia näyttävät samankaltaisilta. Näissä tapauksissa voit mukauttaa kuvausta ohjataksesi reititystä listaamalla erityiset skenaariot, jotka sollten laukaista kunkin siirron.
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.",
),
],
)
Käsienluovutukset kontekstin kanssa
Siirto on hyödyllinen vain, jos vastaanottava agentti tietää, mitä on meneillään. Kun agentti suorittaa käsienluovutuksen, keskusteluhistoria välitetään kohdeagentille: uudella agentilla on pääsy kaikkeen tähän asti sanottuun, joten asiakkaan ei tarvitse toistaa ongelmaansa. Tämän päälle tyypitetty konteksti kuljettaa strukturoitua istuntodataa – asiakastunnus, tilattu suunnitelma, aiemmat tiketit – ja pysyy saavutettavissa saapuvan agentin työkaluille.
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,
)
Kuva: Kolmitasoinen lajittelu
Käsienluovutukset eivät rajoitu horisontaaliseen reititykseen. Ne myös jäljittelevät todellisen tukipalvelun eskalointirakennetta. Tässä on tuotantokäytössä oleva kuvio kolmella tasolla: L1 hoitaa rutiinikyselyt, siirtää edistyneet konfiguraatio-ongelmat tasolle L2, ja L2 eskaloi arkkitehtuuriaiheet tasolle L3. Huomaa, että taso 3 luottaa kyvykkäämpään malliin, koska se näkee vain tapaukset, jotka kaksi edellistä tasoa ovat jo suodattaneet.
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",
)
Kaksisuuntaiset käsienluovutukset
Ketju voi olla myös syklinen: kaksi agenttia voi siirtää valtaa edestakaisin. Tämä on tyypillistä, kun potentiaalinen asiakas esittää teknisen kysymyksen myyntikeskustelun aikana ja palaa sitten hinnoitteluun saatuaan varmistuksen.
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]
Varo äärettömiä silmukoita: suojamekanismi tai max_turns on suositeltavaa. Ilman tätä rajaa epäselvä pyyntö voi pompottaa keskustelua agentilta toiselle, kunnes kiintiösi ehtyy.
Käsienluovutusten seuranta
Lopuksi, sinun on tiedettävä, kuka itse asiassa vastasi – sekä reitityksesi varmentamiseksi että tukitilastojasi varten. RunResult kertoo, kumpi agentti tuotti vastauksen lopulta.
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
Tee tavaksi lokittaa tämä arvo: jos lajitteluagentti pitää hallussaan pyyntöjä, jotka sen olisi pitänyt siirtää eteenpäin, last_agent-jakautuma paljastaa ongelman kauan ennen kuin asiakaspalaute tekee sen.
Keskeiset asiat
- Käsienluovutukset mahdollistavat keskustelun delegoimisen erikoistuneelle agentille
- Keskusteluhistoria välitetään kohdeagentille
- Käytä
Handoff(agent=..., description=...)reitityksen ohjaamiseen - Jaettu konteksti (
RunContextWrapper) on kaikkien agenttien saatavilla result.last_agent.nameilmoittaa, kumpi agentti vastasi lopulta- Suojaa kaksisuuntaiset käsienluovutukset
max_turns-asetuksella silmukoiden estämiseksi