Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Trasferimenti: Orkestrazzjoni ta' Aġenti Multipli

Lezzjoni 12 / 25 Aġġornat 29 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Trasferimenti: Orkestrazzjoni ta’ Aġenti Multipli
  2. Il-Kunċett tat-Trasferiment
  3. Personalizzazzjoni tad-Deskrizzjoni tat-Trasferiment
  4. Trasferimenti bil-Kuntest
  5. Mudell: Triaġġ fuq Tliet Livelli
  6. Trasferimenti Bidirezzjonali
  7. Traċċar tat-Trasferimenti
  8. Punti Ewlenin

Trasferimenti: Orkestrazzjoni ta’ Aġenti Multipli

Aġent wieħed ma jistax jagħmel kollox. Aktar ma żżid oqsma f’sett wieħed ta’ istruzzjonijiet, aktar il-linji gwida jikkontradixxu lil xulxin u r-riżposti jsiru aktar dgħajfa. It-trasferimenti (handoffs) jippermettu lil aġent jiddelega l-konversazzjoni lil aġent ieħor speċjalizzat. Dan huwa l-mekkaniżmu ewlieni biex tibni sistemi multi-aġent fejn kull aġent jeċċella fl-oqsma tiegħu stess.

Il-Kunċett tat-Trasferiment

Trasferiment huwa trasferiment ta’ kontroll minn aġent għal ieħor. Meta l-Aġent A jagħmel trasferiment lill-Aġent B, l-Aġent B jieħu f’idejh u jiġġenera r-risposta. Ir-Runner jimmaniġġja din it-tranżizzjoni awtomatikament: m’għandekx tikteb loġika ta’ routing espliċita jew isejjaħ it-tieni aġent manwalment. Fl-eżempju hawn taħt, l-aġent ta’ triaġġ jirċievi lment dwar ammont ta’ fattura, jirrikonoxxi l-qasam, u jgħaddi l-kompitu. Il-klijent, min-naħa tiegħu, jara biss konversazzjoni kontinwa waħda.

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)

Personalizzazzjoni tad-Deskrizzjoni tat-Trasferiment

B’mod predefinit, trasferiment juża l-isem u l-istruzzjonijiet tal-aġent fil-mira. Dan jaħdem sew sakemm l-ismijiet ikunu deskrittivi, iżda jsir riskjuż meta żewġ aġenti jixbhu lil xulxin. F’dawk il-każijiet, tista’ tippersonalizza d-deskrizzjoni biex tiggwida r-routing billi telenka x-xenarji speċifiċi li għandhom jattivaw kull trasferiment.

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

Trasferimenti bil-Kuntest

Trasferiment huwa utli biss jekk l-aġent li jieħu f’idejh ikun jaf x’inhu għaddej. Meta aġent jagħmel trasferiment, l-istorja tal-konversazzjoni tingħadda lill-aġent fil-mira: l-aġent il-ġdid ikollu aċċess għal kull ma ntqal sa issa, hekk il-klijent ma jkollux jerġa’ jispjega l-problema tiegħu. Barra minn hekk, il-kuntest ittajpjat iġorr data tas-sessjoni strutturata—ID tal-klijent, pjan abbonat, tickets preċedenti—u jibqa’ aċċessibbli għall-għodod tal-aġent li jkun wasal.

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

Mudell: Triaġġ fuq Tliet Livelli

It-trasferimenti mhumiex limitati għar-routing orizzontali. Huma jirriproduċu wkoll l-istruttura ta’ eskalazzjoni ta’ servizz ta’ appoġġ reali. Hawnhekk hemm mudell ta’ produzzjoni b’tliet livelli: L1 jimmaniġġja mistoqsijiet ta’ rutina, jittrasferixxi kwistjonijiet avvanzati ta’ konfigurazzjoni lil L2, u L2 jeskalaw temi ta’ arkitettura lil L3. Innota li l-livell 3 jiddependi fuq mudell aktar kapaċi, peress li jara biss każijiet diġà ffiltrati miż-żewġ livelli preċedenti.

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

Trasferimenti Bidirezzjonali

Il-katina tista’ tkun ċirkolari wkoll: żewġ aġenti jistgħu jittrasferixxu l-kontroll lura u ‘l quddiem. Dan huwa tipiku meta prospett jagħmel mistoqsija teknika waqt konversazzjoni ta’ bejgħ, imbagħad jerġa’ lura għall-prezzijiet ladarba jkun ġie rassigurat.

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]

Oqgħod attent għal loops infiniti: hija rrakkomandata guardrail jew max_turns. Mingħajr dan il-limitu, talba ambigwa tista’ tballunza l-konversazzjoni minn aġent għal ieħor sakemm il-kwota tiegħek tintemm.

Traċċar tat-Trasferimenti

Fl-aħħar nett, għandek bżonn tkun taf min wieġeb verament—kemm biex tivverifika r-routing tiegħek kif ukoll għall-istatistika tal-appoġġ tiegħek. Ir-RunResult jgħidlek liema aġent finalment ipproduċa r-risposta.

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

Agħmilha drawwa li tirreġistra dan il-valur: jekk aġent ta’ triaġġ iżomm il-kontroll fuq talbiet li kellu jittrasferixxi, id-distribuzzjoni ta’ last_agent tikxef il-problema ferm qabel ma jagħmlu l-feedback tal-klijenti.

Punti Ewlenin

  • It-trasferimenti jippermettulek tiddelega l-konversazzjoni lil aġent speċjalizzat
  • L-istorja tal-konversazzjoni tingħadda lill-aġent fil-mira
  • Uża Handoff(agent=..., description=...) biex tiggwida r-routing
  • Il-kuntest kondiviż (RunContextWrapper) huwa aċċessibbli għall-aġenti kollha
  • result.last_agent.name jindika liema aġent wieġeb finalment
  • Ipproteġi t-trasferimenti bidirezzjonali b’max_turns biex tevita l-loops