Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Předávání: Orchestrujeme více agentů

Lekce 12 z 25 Aktualizováno 29. července 2026 Vývojář
Na této stránce
  1. Předávání: Orchestrujeme více agentů
  2. Koncept předávání
  3. Přizpůsobení popisu předávání
  4. Předávání s kontextem
  5. Vzor: Tříúrovňové třídění
  6. Obousměrná předávání
  7. Sledování předávání
  8. Klíčové poznatky

Předávání: Orchestrujeme více agentů

Jeden agent nedokáže všechno. Čím více domén nacpeš do jedné sady instrukcí, tím více se tyto pokyny navzájem rozporují a odpovědi jsou čím dál vlažnější. Předávání (handoffs) umožňují agentovi delegovat konverzaci na jiného specializovaného agenta. To je klíčový mechanismus pro budování systémů s více agenty, kde každý vyniká ve své vlastní doméně.

Koncept předávání

Předávání je přenos řízení z jednoho agenta na druhého. Když Agent A předá konverzaci Agentovi B, přebírá otěže Agent B a generuje odpověď. Runner tento přechod zpracuje automaticky: nemusíš psát explicitní logiku směrování ani ručně volat druhého agenta. V níže uvedeném příkladu přijme třídící agent stížnost na výši faktury, rozpozná doménu a předá štafetu. Zákazník mezitím vidí pouze jednu souvislou konverzaci.

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)

Přizpůsobení popisu předávání

Ve výchozím nastavení používá předávání název cílového agenta a jeho instrukce. To funguje dobře, pokud jsou názvy popisné, ale stává se to riskantním, když si jsou dva agenti podobní. V takových případech můžeš popis přizpůsobit tak, aby směrování vedl výčtem konkrétních scénářů, které by měly každý přenos spustit.

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

Předávání s kontextem

Přenos je užitečný pouze tehdy, pokud přebírající agent ví, o co jde. Když agent provede předání, historie konverzace se předá cílovému agentovi: nový agent má přístup ke všemu, co bylo doposud řečeno, takže zákazník nemusí svůj problém opakovat. K tomu navíc typovaný kontext přenáší strukturovaná data relace – ID zákazníka, předplacený plán, minulý tiket – a zůstává přístupný nástrojům příchozího 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,
)

Vzor: Tříúrovňové třídění

Předávání není omezeno pouze na horizontální směrování. Dokáže také replikovat eskalační strukturu skutečné podpory. Zde je produkční vzor se třemi úrovněmi: L1 řeší běžné dotazy, pokročilé problémy s konfigurací předává na L2 a L2 eskaluje témata architektury na L3. Všimni si, že úroveň 3 spoléhá na schopnější model, protože vidí pouze případy, které již prošly filtrem dvou předchozích úrovní.

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

Obousměrná předávání

Řetězec může být také kruhový: dva agenti si mohou předávat řízení tam a zpět. To je typické, když se potenciální zákazník během obchodního jednání zeptá na technický detail a poté, co je ujištěn, se vrátí 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]

Dej si pozor na nekonečné smyčky: doporučuje se použít ochranný mechanismus nebo max_turns. Bez tohoto limitu může nejednoznačný požadavek přehazovat konverzaci z jednoho agenta na druhého, dokud se nevyčerpá tvůj kvóta.

Sledování předávání

Nakonec potřebuješ vědět, kdo skutečně odpověděl – jednak pro ověření tvého směrování a jednak pro tvoje statistiky podpory. RunResult ti řekne, který agent nakonec vygeneroval odpověď.

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 tuto hodnotu logovat: pokud třídící agent udržuje kontrolu nad požadavky, které měl předat, distribuce last_agent odhalí problém dlouho předtím, než se ozve zpětná vazba od zákazníků.

Klíčové poznatky

  • Předávání ti umožňují delegovat konverzaci na specializovaného agenta
  • Historie konverzace se předá cílovému agentovi
  • Pro vedení směrování použij Handoff(agent=..., description=...)
  • Sdílený kontext (RunContextWrapper) je přístupný všem agentům
  • result.last_agent.name indikuje, který agent nakonec odpověděl
  • Chraň obousměrná předávání pomocí max_turns, abys předešel smyčkám