Przekazywanie zadań: Orkiestracja wielu agentów
Na tej stronie
Przekazywanie zadań: Orkiestracja wielu agentów
Pojedynczy agent nie zrobi wszystkiego. Im więcej domen upchniesz w jednym zestawie instrukcji, tym bardziej będą się one ze sobą kłócić, a odpowiedzi staną się coraz bardziej letnie. Przekazywanie zadań (handoffs) pozwala agentowi delegować rozmowę innemu, wyspecjalizowanemu agentowi. To kluczowy mechanizm budowania systemów wieloagentowych, w których każdy agent exceluje w swojej własnej domenie.
Koncepcja przekazywania zadań
Przekazanie zadania to przeniesienie sterowania z jednego agenta na drugi. Gdy Agent A przekazuje zadanie Agentowi B, to Agent B przejmuje inicjatywę i generuje odpowiedź. Runner obsługuje to przejście automatycznie: nie piszesz jawnej logiki routingu ani nie wywołujesz ręcznie drugiego agenta. W poniższym przykładzie agent triażowy otrzymuje skargę dotyczącą kwoty na fakturze, rozpoznaje domenę i przekazuje pałeczkę dalej. Klient meanwhile widzi tylko jedną, ciągłą rozmowę.
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)
Dostosowywanie opisu przekazywania zadań
Domyślnie przekazanie zadania korzysta z nazwy i instrukcji agenta docelowego. Działa to dobrze, dopóki nazwy są opisowe, ale staje się ryzykowne, gdy dwaj agenci wyglądają podobnie. W takich przypadkach możesz dostosować opis, aby kierować routingiem, wymieniając konkretne scenariusze, które powinny wyzwalać każde przekazanie.
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.",
),
],
)
Przekazywanie zadań z kontekstem
Przekazanie jest użyteczne tylko wtedy, gdy przejmujący agent wie, co się dzieje. Gdy agent wykonuje przekazanie zadania, historia rozmowy jest przekazywana agentowi docelowemu: nowy agent ma dostęp do wszystkiego, co zostało powiedziane do tej pory, więc klient nie musi powtarzać swojego problemu. Do tego dochodzi typowany kontekst, który przenosi strukturalne dane sesji – ID klienta, wykupiony plan, historię zgłoszeń – i pozostaje dostępny dla narzędzi przychodzącego 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,
)
Wzorzec: Trójpoziomowy triaż
Przekazywanie zadań nie ogranicza się do routingu poziomego. Odzwierciedla również strukturę eskalacji prawdziwej usługi wsparcia. Oto wzorzec produkcyjny z trzema poziomami: L1 obsługuje rutynowe zapytania, przekazuje zaawansowane problemy konfiguracyjne do L2, a L2 eskaluje tematy architektoniczne do L3. Zauważ, że poziom 3 opiera się na bardziej wydajnym modelu, ponieważ widzi tylko przypadki już przefiltrowane przez dwa poprzednie poziomy.
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",
)
Dwukierunkowe przekazywanie zadań
Łańcuch może być również cykliczny: dwaj agenci mogą przekazywać sobie sterowanie tam i z powrotem. Jest to typowe, gdy potencjalny klient zadaje pytanie techniczne podczas rozmowy sprzedażowej, a następnie wraca do kwestii cenowych, gdy już się uspokoi.
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]
Uważaj na nieskończone pętle: zalecane jest zastosowanie zabezpieczenia (guardrail) lub parametru max_turns. Bez tego limitu niejednoznaczne żądanie może odbijać rozmowę od jednego agenta do drugiego, aż wyczerpiesz swój limit zużycia.
Śledzenie przekazywania zadań
Na koniec musisz wiedzieć, kto faktycznie odpowiedział – zarówno w celu weryfikacji routingu, jak i dla statystyk wsparcia. RunResult informuje Cię, który agent ostatecznie wygenerował odpowiedź.
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
Wprowadź sobie w nawyk logowanie tej wartości: jeśli agent triażowy nadal przejmuje żądania, które powinien był przekazać, rozkład wartości last_agent ujawni problem na długo zanim zrobią to opinie klientów.
Kluczowe wnioski
- Przekazywanie zadań pozwala delegować rozmowę wyspecjalizowanemu agentowi
- Historia rozmowy jest przekazywana agentowi docelowemu
- Użyj
Handoff(agent=..., description=...), aby kierować routingiem - Wspólny kontekst (
RunContextWrapper) jest dostępny dla wszystkich agentów result.last_agent.namewskazuje, który agent finalnie odpowiedział- Zabezpiecz dwukierunkowe przekazywanie zadań za pomocą
max_turns, aby uniknąć pętli