Предаване на контрол: Оркестриране на множество агенти
На тази страница
Предаване на контрол: Оркестриране на множество агенти
Един единствен агент не може да върши всичко. Колкото повече области натрупате в един набор от инструкции, толкова повече указанията си противоречат и отговорите стават по-безлични. Предаването на контрол (Handoffs) позволява на един агент да делегира разговора на друг специализиран агент. Това е ключовият механизъм за изграждане на мулти-агентни системи, в които всеки агент блести в собствената си област.
Концепцията за предаване на контрол
Предаването на контрол е прехвърляне на управлението от един агент към друг. Когато Агент А предаде контрола на Агент Б, Агент Б поема и генерира отговора. Модулът Runner обработва този преход автоматично: Вие не пишете явна логика за насочване и не извиквате ръчно втория агент. В примера по-долу агентът за триаж получава оплакване относно сума във фактура, разпознава областта и предава щафетата. Междувременно клиентът вижда само един непрекъснат разговор.
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)
Персонализиране на описанието за предаване
По подразбиране предаването на контрол използва името и инструкциите на целевия агент. Това работи добре, стига имената да са описателни, но става рисково, когато два агента си приличат. В такива случаи можете да персонализирате описанието, за да насочите маршрутизирането, като изброите конкретните сценарии, които трябва да задействат всяко прехвърляне.
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.",
),
],
)
Предаване на контрол с контекст
Едно прехвърляне е полезно само ако агентът, който поема, знае какво се случва. Когато един агент извърши предаване на контрол, историята на разговора се предава на целевия агент: новият агент има достъп до всичко казано дотук, така че клиентът не трябва да повтаря проблема си. Освен това типизираният контекст пренася структурирани данни за сесията – ID на клиента, абониран план, предишни тикети – и остава достъпен за инструментите на входящия агент.
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,
)
Шаблон: Триаж на три нива
Предаването на контрол не се ограничава до хоризонтално насочване. То също така възпроизвежда структурата на ескалация в реална служба за поддръжка. Ето един производствен шаблон с три нива: Ниво 1 (L1) обработва рутинни запитвания, прехвърля сложни проблеми с конфигурацията на Ниво 2 (L2), а L2 ескалира теми свързани с архитектурата към Ниво 3 (L3). Обърнете внимание, че ниво 3 разчита на по-мощен модел, тъй като вижда само случаи, вече филтрирани от двете предходни нива.
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",
)
Двупосочно предаване на контрол
Веригата може да бъде и кръгова: два агента могат да си прехвърлят управлението напред-назад. Това е типично, когато потенциален клиент зададе технически въпрос по време на разговор за продажби, след което се върне към темата за цените, след като е успокоен.
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]
Внимавайте за безкрайни цикли: препоръчително е да използвате предпазна мярка или max_turns. Без това ограничение едно двусмислено искане може да прехвърля разговора от един агент на друг, докато квотата Ви не се изчерпи.
Проследяване на предаванията
Накрая, трябва да знаете кой всъщност е отговорил – както за да проверите маршрутизирането си, така и за вашата статистика за поддръжка. Обектът RunResult Ви казва кой агент в крайна сметка е генерирал отговора.
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
Направете си навик да записвате тази стойност: ако агентът за триаж продължава да задържа искания, които е трябвало да прехвърли, разпределението на last_agent ще разкрие проблема много преди обратната връзка от клиентите.
Ключови изводи
- Предаването на контрол Ви позволява да делегирате разговора на специализиран агент
- Историята на разговора се предава на целевия агент
- Използвайте
Handoff(agent=..., description=...), за да насочите маршрутизирането - Споделеният контекст (
RunContextWrapper) е достъпен за всички агенти result.last_agent.nameпоказва кой агент е отговорил най-накрая- Защитете двупосочните предавания с
max_turns, за да предотвратите цикли