Wykonanie po stronie serwera kontra klienta
Na tej stronie
Lekcja zaktualizowana 3 listopada 2026 w oparciu o SDK
mistralaiw wersji 3.7.0 oraz dokumentację Mistral dotyczącą Handoffs: wpisagent.handoffidentyfikuje agenta docelowego poprzeznext_agent_id(a nieto_agent), a metodaconversations.appendnie przyjmuje parametruagent_id– starszy kod zakończy się błędem. Wznowienie działania przez agenta docelowego następuje tutaj w ramach nowej konwersacji, do której przekazujesz kontekst. Źródła: Handoffs · client-python.
Dwa sposoby obsługi przekazywania zadań
Gdy agent przekazuje sterowanie innemu agentowi, API Mistral oferuje dwa tryby wykonania: serwerowy (automatyczny) i kliencki (ręczny). To ustawienie to jedno słowo, ale decyduje ono o tym, kto faktycznie napędza przepływ pracy. W trybie serwerowym delegujesz całą choreografię na rzecz Mistral i otrzymujesz wynik. W trybie klienckim odzyskujesz kontrolę po każdym kroku. Wszystko inne – agenci, ich narzędzia, cele przekazań – pozostaje dokładnie takie samo.
Tryb serwerowy, domyślny
response = client.beta.conversations.start(
agent_id=router_agent.id,
inputs="Analyze and calculate market trends.",
handoff_execution="server" # Domyślnie — można pominąć
)
Przepływ jest w pełni zarządzany: router otrzymuje żądanie, decyduje o przekazaniu do agenta badawczego, a Mistral wykonuje to przekazanie; agent badawczy wykonuje swoją pracę, a następnie przekazuje zadanie do kalkulatora, a Mistral wykonuje również to działanie; kalkulator generuje wynik. Otrzymujesz ostateczną odpowiedź, wraz ze wszystkimi wynikami pośrednimi – widzisz więc, co się stało, ale post factum.
Tryb ten ma trzy cechy, które wyjaśniają, dlaczego jest domyślny. Jest prosty, ponieważ nie piszesz żadnej logiki sterowania po swojej stronie. Jest szybki, ponieważ cały łańcuch wykonuje się w środowisku Mistral bez rund sieciowych przy każdym przekaźniku. Jest niezawodny, gdyż obsługa błędów i limity czasowe między agentami są realizowane za Ciebie.
Jego ograniczenia są dokładnym odwzorowaniem tych zalet. Nie masz żadnej kontroli pośredniej: niemożliwe jest zweryfikowanie lub zmodyfikowanie przekazania w trakcie jego trwania. Koszt jest nieprzejrzysty w tym sensie, że wszyscy agenci w łańcuchu wykonują się bez możliwości przerwania w połowie przepływu żądania zmierzającego w niepotrzebnym kierunku. Nie możesz też wstawić żadnej niestandardowej logiki między krokami – brak szczegółowego logowania, walidacji czy decyzji biznesowych.
Tryb kliencki, gdy potrzebujesz kontroli
response = client.beta.conversations.start(
agent_id=router_agent.id,
inputs="Analyze the cloud market.",
handoff_execution="client"
)
Router otrzymuje żądanie i decyduje o przekazaniu, dokładnie jak wcześniej. Zamiast jednak wykonać przekazanie, otrzymujesz zdarzenie agent.handoff, a łańcuch zatrzymuje się w tym miejscu. To do Ciebie należy ponowne uruchomienie procesu poprzez wywołanie agenta docelowego – co pozostawia Ci swobodę walidacji, logowania, wzbogacenia kontekstu lub po prostu odmowy.
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}")
# Zweryfikuj, a następnie przekaż do agenta docelowego z użytecznym kontekstem
next_response = client.beta.conversations.start(
agent_id=target_agent_id,
inputs="Search for the latest tech news.",
)
# Przetwórz odpowiedź agenta docelowego
for next_entry in next_response.outputs:
print(f"{next_entry.type}: {next_entry.content}")
Jeden punkt zasługuje na uwagę: dokumentacja Mistral opisuje tryb client – kontrola wraca do Ciebie w momencie przekazania – ale nie udostępnia metody, aby agent docelowy wznowił tę samą konwersację, a metoda conversations.append nie przyjmuje parametru agent_id. Przykład dlatego rozpoczyna konwersację z agentem docelowym, któremu jawnie przekazujesz to, czego potrzebuje: oryginalne żądanie oraz, w stosownych przypadkach, podsumowanie tego, co już zostało zrobione. To także okazja, by przekazać tylko to, co agent musi zobaczyć.
Powyższy fragment obsługuje tylko jedno przekazanie. Prawdziwy łańcuch łączy ich kilka, co wymaga pętli.
def execute_with_control(router_id, query):
"""Wykonuje przepływ pracy wielu agentów z kontrolą na każdym kroku."""
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] Przekazanie do {target}")
# Tutaj możesz dodać: walidację, logowanie, metryki
response = client.beta.conversations.start(
agent_id=target,
inputs=query, # oryginalne żądanie, wzbogacone w razie potrzeby
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
Struktura przypomina pompę: dopóki w wynikach pojawia się przekazanie, przetwarzasz je i restartujesz; gdy tylko iteracja pętli nie znajdzie żadnego przekazania, łańcuch jest zakończony i wychodzisz z zebranymi wiadomościami. Komentarz w środku oznacza miejsce, które uzasadnia cały ten tryb: to właśnie tam, i tylko tam, Twój kod wstawia się między dwóch agentów.
Wybór między obiema opcjami
Tryb serwerowy pokrywa standardową produkcję. Jeśli Twój przepływ pracy jest przewidywalny, jeśli ufasz agentom, których napisałeś, lub jeśli tworzysz prototyp i chcesz szybko zobaczyć wyniki, pełna automatyzacja jest właściwym wyborem – a pisanie pętli sterującej byłoby stratą czasu.
Tryb kliencki jest uzasadniony, gdy tylko w łańcuchu pojawi się wymóg zewnętrzny. Walidacja przez człowieka, gdy operator musi zatwierdzić przekazanie do agenta wyzwalającego wrażliwe działania. Potrzeba logowania i audytu, gdy zgodność wymaga śledzenia każdego kroku z własnymi identyfikatorami i znacznikami czasu. Routing warunkowy, gdy decyzja zależy od reguł biznesowych, których model nie może znać – status klienta, pora dnia, limit quota. Limit lub ograniczenie częstotliwości (rate limiting), gdy chcesz ograniczyć liczbę agentów wykonanych dla danego żądania. Strategia awaryjna (fallback), wreszcie, gdy awaria jednego agenta musi uruchomić coś innego niż błąd wyświetlony użytkownikowi.
Oto jak wygląda pierwsza z tych sytuacji, sprowadzona do szkieletu.
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"Zezwolić na przekazanie do {target}? (y/n) ")
if approval.lower() == "y":
response = client.beta.conversations.start(
agent_id=target,
inputs=query,
)
else:
print("Przekazanie odrzucone.")
break
Funkcja input w konsoli służy jako demonstracja; w aplikacji zostanie zastąpiona powiadomieniem dla operatora i wznowieniem przepływu pracy po otrzymaniu odpowiedzi. Zasada pozostaje ta sama: przekazanie następuje tylko wtedy, gdy Twój kod je wyzwoli.
Właściwym podejściem jest rozpoczęcie w trybie serwerowym i przełączenie się tylko w dniu, gdy konkretny wymóg tego zażąda. Przełączanie się na tryb kliencki „na wszelki wypadek“ sprawia, że natychmiast płacisz za złożoność pętli i rundy sieciowe, za kontrolę, z której jeszcze nie korzystasz.
Kluczowe wnioski
- Tryb serwerowy = w pełni automatyczny, prosty i szybki, brak kontroli pośredniej
- Tryb kliencki = otrzymujesz zdarzenia przekazania i decydujesz, co zrobić
- Tryb kliencki umożliwia walidację, logowanie, routing warunkowy i obsługę błędów
- W większości przypadków tryb serwerowy wystarcza – przełącz się na tryb kliencki, gdy potrzebujesz kontroli
- Oba tryby obsługują te same łańcuchy agentów; różni się tylko sposób sterowania