Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Odovzdávania: Orchestrovanie viacerých agentov

Lekcia 12 z 25 Aktualizované 29. júla 2026 Vývojár
Na tejto strane
  1. Odovzdávania: Orchestrovanie viacerých agentov
  2. Koncept odovzdania
  3. Prispôsobenie popisu odovzdania
  4. Odovzdávania s kontextom
  5. Vzorec: Trojúrovňová triáž
  6. Obojsmerné odovzdávania
  7. Sledovanie odovzdaní
  8. Kľúčové poznatky

Odovzdávania: Orchestrovanie viacerých agentov

Jeden agent nedokáže všetko. Čím viac domén natlačíš do jednej sady inštrukcií, tým viac sa tieto smernice navzájom protirečia a odpovede sú mdlšie. Odovzdávania (Handoffs) umožňujú agentovi delegovať konverzáciu na iného špecializovaného agenta. Toto je kľúčový mechanizmus pre budovanie systémov s viacerými agentmi, kde každý agent vyniká vo svojej vlastnej doméne.

Koncept odovzdania

Odovzdanie je prenos riadenia z jedného agenta na druhého. Keď Agent A odovzdá konverzáciu Agentovi B, preberá kontrolu Agent B a generuje odpoveď. Nástroj Runner tento prechod vybaví automaticky: nemusíš písať explicitnú logiku smerovania ani ručne volať druhého agenta. V nižšie uvedenom príklade triážny agent dostane sťažnosť na výšku faktúry, rozpozná doménu a odovzdá štafetu. Zákazník medzitým vidí len jednu súvislú konverzáciu.

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)

Prispôsobenie popisu odovzdania

Predvolene odovzdanie používa názov cieľového agenta a jeho inštrukcie. To funguje dobre, pokiaľ sú názvy výstižné, ale stáva sa to rizikovým, keď si sú dvaja agenti podobní. V takýchto prípadoch môžeš popis prispôsobiť tak, aby smerovanie viedol výpočtom konkrétnych scenárov, ktoré by mali spustiť každý 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.",
        ),
    ],
)

Odovzdávania s kontextom

Prenos je užitočný len vtedy, ak prevzatý agent vie, o čo ide. Keď agent vykoná odovzdanie, história konverzácie sa odovzdá cieľovému agentovi: nový agent má prístup ku všetkému, čo bolo doteraz povedané, takže zákazník nemusí svoj problém opakovať. Navyše typovaný kontext prenáša štruktúrované údaje o relácii – ID zákazníka, predplatený plán, minulé tickety – a zostáva dostupný pre nástroje prichádzajúceho 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: Trojúrovňová triáž

Odovzdávania nie sú obmedzené len na horizontálne smerovanie. Dokážu tiež replikovať eskalačnú štruktúru skutočnej podpornej služby. Tu je produkčný vzorec s tromi úrovňami: L1 vybavuje bežné dopyty, pokročilé problémy s konfiguráciou presúva na L2 a L2 eskaluje témy týkajúce sa architektúry na L3. Všimni si, že úroveň 3 sa spolieha na schopnejší model, keďže vidí iba prípady, ktoré už prefiltrovali dve predchádzajúce úrovne.

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",
)

Obojsmerné odovzdávania

Reťazec môže byť aj cyklický: dvaja agenti si môžu navzájom odovzdávať kontrolu. Toto je typické, keď sa potenciálny zákazník počas obchodného rozhovoru opýta na technickú otázku a potom sa po uistení vráti k cenám.

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]

Dávaj pozor na nekonečné slučky: odporúča sa ochranný mechanizmus alebo max_turns. Bez tohto limitu môže nejednoznačná požiadavka hádzať konverzáciu z jedného agenta na druhého, až kým sa nevyčerpá tvoja kvóta.

Sledovanie odovzdaní

Nakoniec potrebuješ vedieť, kto skutočne odpovedal – jednak na overenie tvojej logiky smerovania a jednak pre tvoje štatistiky podpory. Objekt RunResult ti povie, ktorý agent nakoniec vygeneroval odpoveď.

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

Zvykni si túto hodnotu logovať: ak triážny agent stále drží kontrolu nad požiadavkami, ktoré mal odovzdať, distribúcia last_agent odhalí problém oveľa skôr, než to urobí spätná väzba od zákazníkov.

Kľúčové poznatky

  • Odovzdávania ti umožňujú delegovať konverzáciu na špecializovaného agenta
  • História konverzácie sa odovzdáva cieľovému agentovi
  • Na smerovanie používaj Handoff(agent=..., description=...)
  • Zdieľaný kontext (RunContextWrapper) je prístupný všetkým agentom
  • result.last_agent.name indikuje, ktorý agent nakoniec odpovedal
  • Chráň obojsmerné odovzdávania pomocou max_turns, aby sa predišlo slučkám