Predaje: Orkestracija več agentov
Na tej strani
Predaje: Orkestracija več agentov
En sam agent ne zmore vsega. Več domen, kot natrpaš v en nabor navodil, bolj si ta navodila nasprotujejo in bolj mlahavi postanejo odzivi. Predaje omogočajo agentu, da pogovor preda drugemu specializiranemu agentu. To je ključni mehanizem za gradnjo večagentnih sistemov, kjer vsak agent izstopa na svojem področju.
Koncept predaje
Predaja je prenos nadzora z enega agenta na drugega. Ko agent A predaja agentu B, prevzame agent B in ustvari odziv. Runner ta prehod obravnava samodejno: ne pišeš eksplicitne logike usmerjanja niti ročno ne kličeš drugega agenta. V spodnjem primeru agent za triažo prejme pritožbo glede zneska na računu, prepozna domeno in predaja štafeto. Kupec medtem vidi le en neprekinjen pogovor.
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)
Prilagajanje opisa predaje
Privzeto predaja uporabi ime in navodila ciljnega agenta. To deluje dobro, dokler so imena opisna, a postane tvegano, ko sta si dva agenta podobna. V takih primerih lahko prilagodiš opis, da usmeriš usmerjanje z naštevanjem specifičnih scenarijev, ki naj sprožijo vsak prenos.
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.",
),
],
)
Predaje s kontekstom
Prenos je koristen le, če agent, ki prevzame, ve, kaj se dogaja. Ko agent izvede predajo, se zgodovina pogovora prenese na ciljnega agenta: novi agent ima dostop do vsega doslej povedanega, zato kupcu ni treba ponavljati svoje težave. Poleg tega tipizirani kontekst prenaša strukturirane podatke seje – ID stranke, naročniški paket, pretekle primere – in ostaja dostopen orodjem prihajajočega agenta.
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,
)
Vzorec: Triaža na treh ravneh
Predaje niso omejene na vodoravno usmerjanje. Prav tako reproducirajo strukturo eskalacije prave podpore. Tu je produkcijski vzorec s tremi ravnmi: L1 obravnava rutinska vprašanja, napredne težave s konfiguracijo preda na L2, L2 pa teme arhitekture eskalira na L3. Upoštevaj, da raven 3 temelji na zmogljivejšem modelu, saj vidi le primere, ki so jih že filtrirali dve predhodni stopnji.
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",
)
Dvosmerne predaje
Veriga je lahko tudi krožna: dva agenta si lahko izmenično prenašata nadzor. To je značilno, ko potencialni kupec med prodajnim pogovorom zastavi tehnično vprašanje, nato pa se po pomirjenosti vrne k cenam.
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]
Pazi na neskončne zanke: priporočljiva je zaščitna ograja ali max_turns. Brez te omejitve lahko dvoumno zahtevo meče pogovor od enega agenta do drugega, dokler se tvoja kvota ne izčrpa.
Sledenje predajam
Nazadnje moraš vedeti, kdo je dejansko odgovoril – tako za preverjanje usmerjanja kot za tvojo statistiko podpore. RunResult ti pove, kateri agent je nazadnje ustvaril odziv.
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
Naj ti bo v navadi beleženje te vrednosti: če agent za triažo obdrži nadzor nad zahtevami, ki bi jih moral predati, bo porazdelitev last_agent razkrila težavo dolgo pred povratnimi informacijami strank.
Ključne ugotovitve
- Predaje ti omogočajo, da pogovor delegiraš specializiranemu agentu
- Zgodovina pogovora se prenese na ciljnega agenta
- Uporabi
Handoff(agent=..., description=...)za usmerjanje - Skupni kontekst (
RunContextWrapper) je dostopen vsem agentom result.last_agent.namekaže, kateri agent je končno odgovoril- Dvosmerne predaje zaščiti z
max_turns, da preprečiš zanke