Nodevas: vairāku aģentu orķestrēšana
Šajā lapā
Nodevas: vairāku aģentu orķestrēšana
Viens pats aģents nespēj paveikt visu. Jo vairāk domēnu tu iekļauj vienā instrukciju kopā, jo biežāk vadlīnijas nonāk pretrunā un atbildes kļūst arvien vājākas. Nodevas ļauj aģentam nodot sarunu citam specializētam aģentam. Tas ir galvenais mehānisms daudzaģentu sistēmu veidošanai, kur katrs aģents izceļas savā domēnā.
Nodevas jēdziens
Nodeva ir kontroles nodošana no viena aģenta citam. Kad Aģents A nodod sarunu Aģentam B, Aģents B pārņem vadību un ģenerē atbildi. Runner šo pāreju apstrādā automātiski: tev nav jāraksta eksplicita maršrutēšanas loģika vai manuāli jāizsauc otrais aģents. Tālāk redzamajā piemērā triāžas aģents saņem sūdzību par rēķina summu, atpazīst domēnu un nodod estafetes kociņu. Savukārt klients redz tikai vienu nepārtrauktu sarunu.
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)
Nodevas apraksta pielāgošana
Pēc noklusējuma nodeva izmanto mērķa aģenta nosaukumu un instrukcijas. Tas darbojas labi, kamēr nosaukumi ir aprakstoši, taču kļūst riskanti, ja divi aģenti izskatās līdzīgi. Šādos gadījumos tu vari pielāgot aprakstu, lai virzītu maršrutēšanu, uzskaitot konkrētus scenārijus, kuriem jāizraisa katra nodošana.
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.",
),
],
)
Nodevas ar kontekstu
Nodošana ir noderīga tikai tad, ja pārņemošais aģents zina, kas notiek. Kad aģents veic nodevu, sarunas vēsture tiek nodota mērķa aģentam: jaunajam aģentam ir piekļuve visam līdz šim teiktajam, tāpēc klientam nav jāatkārto sava problēma. Turklāt tipēts konteksts pārnēsā strukturētus sesijas datus — klienta ID, abonēto plānu, iepriekšējos biļešu ierakstus — un paliek pieejams ienākošā aģenta rīkiem.
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,
)
Modelis: trīs līmeņu triāža
Nodevas neaprobežojas tikai ar horizontālu maršrutēšanu. Tās arī atveido reāla atbalsta dienesta eskalācijas struktūru. Lūk, ražošanas modelis ar trim līmeņiem: L1 apstrādā ikdienas jautājumus, nodod sarežģītus konfigurācijas jautājumus L2, un L2 eskalē arhitektūras tēmas uz L3. Ņem vērā, ka 3. līmenis paļaujas uz spējīgāku modeli, jo tas redz tikai gadījumus, kurus jau ir filtrējuši divi iepriekšējie līmeņi.
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",
)
Divvirzienu nodevas
Ķēde var būt arī cikliska: divi aģenti var nodot kontroli uz priekšu un atpakaļ. Tas ir tipiski, ja potenciālais klients pārdošanas sarunas laikā uzdod tehnisku jautājumu un pēc tam, kad ir pārliecināts, atgriežas pie cenu jautājumiem.
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]
Uzmanies no bezgalīgām cilpām: ir ieteicams izmantot aizsardzības mehānismu vai max_turns. Bez šī ierobežojuma neskaidrs pieprasījums var likt sarunai lēkāt no viena aģenta uz otru, līdz tava kvota ir izsmelta.
Nodevu izsekošana
Visbeidzot, tev ir jāzina, kurš patiesībā sniedza atbildi — gan lai pārbaudītu savu maršrutēšanu, gan savu atbalsta statistiku. RunResult norāda, kurš aģents galu galā ģenerēja atbildi.
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
Ieradini sevi reģistrēt šo vērtību: ja triāžas aģents patur kontroli pār pieprasījumiem, kurus tam vajadzētu būt nodevušam, last_agent sadalījums atklās problēmu krietni pirms klientu atsauksmēm.
Galvenās atziņas
- Nodevas ļauj nodot sarunu specializētam aģentam
- Sarunas vēsture tiek nodota mērķa aģentam
- Izmanto
Handoff(agent=..., description=...), lai virzītu maršrutēšanu - Koplietots konteksts (
RunContextWrapper) ir pieejams visiem aģentiem result.last_agent.namenorāda, kurš aģents beigās atbildēja- Aizsargā divvirzienu nodevas ar
max_turns, lai novērstu cilpas