Execuție pe server vs. client
Pe această pagină
Lecție actualizată la 3 noiembrie 2026 pe baza SDK-ului
mistralai3.7.0 și a documentației Mistral Handoffs: o intrareagent.handoffidentifică agentul țintă prinnext_agent_id(nuto_agent), iarconversations.appendnu acceptă un parametruagent_id—codul mai vechi ar eșua. Reluarea activității agentului țintă se face aici printr-o nouă conversație, căreia îi transmiteți contextul. Surse: Handoffs · client-python.
Două moduri de gestionare a transferurilor
Când un agent transferă controlul către un alt agent, API-ul Mistral oferă două moduri de execuție: server (automat) și client (manual). Setarea constă într-un singur cuvânt, dar determină cine conduce efectiv fluxul de lucru. În modul server, delegați întreaga coregrafie către Mistral și primiți rezultatul. În modul client, recâștigați controlul între fiecare pas. Tot restul—agenții, instrumentele lor, țintele de transfer—rămâne exact la fel.
Modul server, opțiunea implicită
response = client.beta.conversations.start(
agent_id=router_agent.id,
inputs="Analyze and calculate market trends.",
handoff_execution="server" # Implicit — poate fi omis
)
Fluxul este gestionat integral: routerul primește cererea, decide transferul către agentul de cercetare, iar Mistral execută transferul; agentul de cercetare își face treaba, apoi transferă către calculator, iar Mistral execută și acest pas; calculatorul produce rezultatul. Primești răspunsul final, însoțit de toate ieșirile intermediare—așadar vedeți ce s-a întâmplat, dar post-factum.
Acest mod are trei calități care explică de ce este implicit. Este simplu, deoarece nu scrieți nicio logică de control din partea dumneavoastră. Este rapid, deoarece întregul lanț se execută la Mistral fără dus-întorsuri de rețea la fiecare releu. Este fiabil, deoarece gestionarea erorilor și timeout-urile între agenți sunt asigurate pentru dumneavoastră.
Limitările sale sunt exact contrapartida acestora. Nu aveți niciun control intermediar: este imposibil să validați sau să modificați un transfer în timp ce acesta are loc. Costul este opac, în sensul că toți agenții din lanț se execută fără ca dumneavoastră să puteți întrerupe la jumătatea fluxului o cerere care se îndreaptă într-o direcție inutilă. Și nu puteți introduce nicio logică personalizată între pași—fără jurnalizare detaliată, fără validare, fără decizii de business.
Modul client, când doriți control
response = client.beta.conversations.start(
agent_id=router_agent.id,
inputs="Analyze the cloud market.",
handoff_execution="client"
)
Routerul primește cererea și decide transferul, exact ca înainte. Dar în loc ca transferul să se execute, primiți un eveniment agent.handoff, iar lanțul se oprește acolo. Depinde de dumneavoastră să îl reporniți apelând agentul țintă—ceea ce vă lasă libertatea de a valida, de a jurnaliza, de a îmbogăți contextul sau pur și simplu de a refuza.
response = client.beta.conversations.start(
agent_id=router_agent.id,
inputs="Search for the latest tech news.",
handoff_execution="client"
)
for entry in response.outputs:
if entry.type == "agent.handoff":
target_agent_id = entry.next_agent_id
print(f"Handoff requested to: {target_agent_id}")
# Validați, apoi predați controlul agentului țintă, cu context util
next_response = client.beta.conversations.start(
agent_id=target_agent_id,
inputs="Search for the latest tech news.",
)
# Procesați răspunsul agentului țintă
for next_entry in next_response.outputs:
print(f"{next_entry.type}: {next_entry.content}")
Un aspect merită atenție: documentația Mistral descrie modul client—controlul revine la dumneavoastră la momentul transferului—dar nu oferă nicio metodă pentru ca agentul țintă să reia aceeași conversație, iar conversations.append nu acceptă un parametru agent_id. Exemplul pornește therefore o conversație cu agentul țintă, căruia îi transmiteți explicit ceea ce are nevoie: cererea originală și, dacă este cazul, un rezumat al ceea ce s-a făcut deja. Aceasta este, de asemenea, o oportunitate de a transmite doar ceea ce trebuie să vadă.
Fragmentul de mai sus gestionează doar un singur releu. Un lanț real leagă mai mulți, ceea ce necesită o buclă.
def execute_with_control(router_id, query):
"""Execută un flux de lucru multi-agent cu control la fiecare pas."""
response = client.beta.conversations.start(
agent_id=router_id,
inputs=query,
handoff_execution="client"
)
conversation_id = response.conversation_id
results = []
while True:
handoff_found = False
for entry in response.outputs:
if entry.type == "agent.handoff":
handoff_found = True
target = entry.next_agent_id
print(f"[LOG] Transfer către {target}")
# Aici puteți adăuga: validare, jurnalizare, metrici
response = client.beta.conversations.start(
agent_id=target,
inputs=query, # cererea originală, îmbogățită dacă este nevoie
handoff_execution="client",
)
conversation_id = response.conversation_id
break
elif entry.type == "message.output":
results.append(entry.content)
if not handoff_found:
break
return results
Structura este cea a unei pompe: atâta timp cât un transfer apare în ieșiri, îl procesați și reporniți; de îndată ce o iterație a buclei nu găsește niciunul, lanțul s-a terminat și ieșiți cu mesajele acumulate. Comentariul din mijloc marchează locația care justifică întregul acest mod: doar acolo, și nicăieri altundeva, codul dumneavoastră se interpune între doi agenți.
Alegerea între cele două
Modul server acoperă producția standard. Dacă fluxul dumneavoastră de lucru este predictibil, dacă aveți încredere în agenții pe care i-ați scris sau dacă faceți prototipare și doriți să vedeți rezultate rapid, automatizarea completă este alegerea corectă—iar scrierea unei bucle de control ar fi un efort risipit.
Modul client se justifică de îndată ce o cerință externă intră în lanț. Validare umană, când un operator trebuie să aprobe un transfer către un agent care declanșează acțiuni sensibile. Necesitatea de jurnalizare și audit, când conformitatea impune trasarea fiecărui pas cu propriii identificatori și propriile timestamp-uri. Rutare condiționată, când decizia depinde de reguli de business pe care modelul nu le poate cunoaște—statutul clientului, ora din zi, o cotă. O limită superioară, sau rate limiting, când doriți să limitați numărul de agenți executați pentru o cerere. O strategie de fallback, în final, când eșecul unui agent trebuie să declanșeze altceva decât o eroare afișată utilizatorului.
Iată cum arată prima dintre aceste situații, redusă la scheletul său.
def workflow_with_validation(router_id, query):
response = client.beta.conversations.start(
agent_id=router_id,
inputs=query,
handoff_execution="client"
)
for entry in response.outputs:
if entry.type == "agent.handoff":
target = entry.next_agent_id
approval = input(f"Authorize transfer to {target}? (y/n) ")
if approval.lower() == "y":
response = client.beta.conversations.start(
agent_id=target,
inputs=query,
)
else:
print("Transfer refused.")
break
Funcția input din consolă servește ca demonstrație; într-o aplicație, aceasta va fi înlocuită de o notificare către un operator și de reluarea fluxului de lucru la sosirea răspunsului. Principiul rămâne același: transferul are loc doar dacă codul dumneavoastră îl declanșează.
Abordarea corectă este să începeți în modul server și să comutați doar în ziua în care o constrângere specifică o impune. Trecerea la modul client „doar în caz“ vă face să plătiți imediat pentru complexitatea unei bucle și pentru dus-întorsurile de rețea, pentru un control pe care nu îl utilizați încă.
Puncte cheie
- Modul server = complet automat, simplu și rapid, fără control intermediar
- Modul client = primiți evenimente de transfer și decideți ce să faceți
- Modul client permite validarea, jurnalizarea, rutarea condiționată și gestionarea erorilor
- Pentru majoritatea cazurilor, modul server este suficient—comutați la modul client când aveți nevoie de control
- Ambele moduri suportă aceleași lanțuri de agenți; doar controlul diferă