Suoritus palvelimella vs. asiakkaalla
Tällä sivulla
Oppitunti päivitetty 3. marraskuuta 2026 perustuen
mistralaiSDK:n versioon 3.7.0 ja Mistralin Handoffs-dokumentaatioon:agent.handoff-merkintä tunnistaa kohdeagentin käyttämällänext_agent_id:tä (eito_agent), eikäconversations.appendhyväksyagent_id-parametria – vanhempi koodi epäonnistuisi. Kohdeagentin jatkaminen tapahtuu tässä uudessa keskustelussa, jolle välität kontekstin. Lähteet: Handoffs · client-python.
Kaksi tapaa hallita luovutuksia
Kun agentti siirtää ohjauksen toiselle agentille, Mistral API tarjoaa kaksi suoritustilaa: palvelin (automaattinen) ja asiakas (manuaalinen). Asetus on yksi sana, mutta se määrittää, kuka todellisuudessa ohjaa työnkulkua. Palvelintilassa delegoit koko koreografian Mistralille ja vastaanotat tuloksen. Asiakastilassa saat ohjauksen takaisin jokaisen vaiheen välissä. Kaikki muu – agentit, niiden työkalut ja luovutuskohteet – pysyy täsmälleen samana.
Palvelintila, oletusarvo
response = client.beta.conversations.start(
agent_id=router_agent.id,
inputs="Analyze and calculate market trends.",
handoff_execution="server" # Oletus – voidaan jättää pois
)
Virta hallitaan täysin: reititin vastaanottaa pyynnön, päättää siirtää tutkimusagentille, ja Mistral suorittaa siirron; tutkimusagentti tekee työnsä ja siirtää sitten laskimelle, ja Mistral suorittaa myös tämän; laskin tuottaa tuloksen. Vastaanotat lopullisen vastauksen, jonka mukana tulevat kaikki välivaiheiden tulokset – näet siis mitä tapahtui, mutta jälkikäteen.
Tällä tilalla on kolme ominaisuutta, jotka selittävät, miksi se on oletusarvo. Se on yksinkertainen, koska et kirjoita mitään ohjauslogiikkaa omalle puolellesi. Se on nopea, koska koko ketju suoritetaan Mistralissa ilman verkkokierroksia jokaisen välivaiheen kohdalla. Se on luotettava, sillä virheenkäsittely ja aikakatkaisut agenttien välillä hoidetaan puolestasi.
Sen rajoitukset ovat näiden etujen kääntöpuoli. Sinulla ei ole välivaiheiden ohjausta: luovutusta on mahdotonta validoida tai muokata sen tapahtuessa. Kustannukset ovat läpinäkymättömiä siinä mielessä, että kaikki ketjun agentit suoritetaan ilman mahdollisuutta keskeyttää pyyntöä kesken virtauksen, jos se suuntautuu tarpeettomaan suuntaan. Et myöskään voi lisätä mukautettua logiikkaa vaiheiden väliin – ei hienojakoista lokitusta, validointia eikä liiketoimintapäätöksiä.
Asiakastila, kun haluat ohjausta
response = client.beta.conversations.start(
agent_id=router_agent.id,
inputs="Analyze the cloud market.",
handoff_execution="client"
)
Reititin vastaanottaa pyynnön ja päättää siirrosta aivan kuten ennenkin. Siirron suorittamisen sijaan vastaanotat kuitenkin agent.handoff-tapahtuman, ja ketju pysähtyy siihen. Sinun tehtäväsi on käynnistää se uudelleen kutsumalla kohdeagenttia – tämä antaa sinulle vapauden validoida, lokittaa, rikastaa kontekstia tai yksinkertaisesti kieltäytyä.
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}")
# Validoi ja siirrä sitten kohdeagentille hyödyllisen kontekstin kera
next_response = client.beta.conversations.start(
agent_id=target_agent_id,
inputs="Search for the latest tech news.",
)
# Käsittele kohdeagentin vastaus
for next_entry in next_response.outputs:
print(f"{next_entry.type}: {next_entry.content}")
Yksi kohta ansaitsee huomiota: Mistralin dokumentaatio kuvailee client-tilaa – ohjaus palautuu sinulle siirtohetkellä – mutta se ei tarjoa menetelmää, jolla kohdeagentti jatkaisi samaa keskustelua, eikä conversations.append hyväksy agent_id-parametria. Esimerkki käynnistääkin keskustelun kohdeagentin kanssa, jolle välität eksplisiittisesti sen tarvitsemat tiedot: alkuperäisen pyynnön ja tarvittaessa yhteenvedon jo tehdystä työstä. Tämä on myös tilaisuus välittää vain se, mitä niiden tarvitsee nähdä.
Yllä oleva koodinpätkä käsittelee vain yhden siirron. Todellinen ketju linkittää useita, mikä edellyttää silmukkaa.
def execute_with_control(router_id, query):
"""Suorittaa usean agentin työnkulun ohjauksen kera jokaisessa vaiheessa."""
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] Handoff to {target}")
# Tähän voit lisätä: validoinnin, lokituksen, mittarit
response = client.beta.conversations.start(
agent_id=target,
inputs=query, # alkuperäinen pyyntö, rikastettuna tarvittaessa
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
Rakenne on kuin pumpun: niin kauan kuin tulosteissa ilmenee luovutus, käsittelet sen ja käynnistät uudelleen; heti kun silmukan kierros ei löydä yhtään, ketju on valmis ja poistut kertyneiden viestien kera. Keskellä oleva kommentti merkitsee kohtaa, joka oikeuttaa koko tämän tilan: juuri tässä, ja vain tässä, koodisi asettuu kahden agentin väliin.
Valinta kahden välillä
Palvelintila kattaa tavanomaisen tuotantokäytön. Jos työnkulusi on ennustettava, jos luotat kirjoittamiisi agentteihin tai jos teet prototyyppiä ja haluat nähdä tulokset nopeasti, täysi automaatio on oikea valinta – ohjaussilmukan kirjoittaminen olisi turhaa vaivaa.
Asiakastila on perusteltu heti, kun ketjuun astuu ulkoinen vaatimus. Ihmisvalidointi, kun operaattorin on hyväksyttävä siirto agentille, joka laukaisee arkaluonteisia toimia. Lokitus- ja auditointitarve, kun vaatimustenmukaisuus edellyttää jokaisen vaiheen jäljittämistä omilla tunnisteillasi ja omilla aikaleimoillasi. Ehdollinen reititys, kun päätös riippuu liiketoimintasäännöistä, joita malli ei voi tietää – asiakkaan status, vuorokaudenaika, kiintiö. Katto tai nopeusrajoitus, kun haluat rajoittaa pyyntöä kohden suoritettavien agenttien määrää. Lopuksi varasuunnitelma, kun yhden agentin epäonnistumisen on käynnistettävä jotain muuta kuin käyttäjälle näytettävä virhe.
Tässä on näistä tilanteista ensimmäinen, pelkistettynä luurankoonsa.
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
Konsolin input toimii demonstraationa; sovelluksessa se korvataan ilmoituksella operaattorille ja työnkulun jatkamisella vastauksen saapuessa. Periaate pysyy samana: siirto tapahtuu vain, jos koodisi laukaisee sen.
Oikea lähestymistapa on aloittaa palvelintilassa ja vaihtaa vasta sinä päivänä, kun tietty rajoite sitä vaatii. Siirtyminen asiakastilaan “varmuuden vuoksi” saa sinut maksamaan heti silmukan monimutkaisuudesta ja verkkokierroksista ohjauksesta, jota et vielä käytä.
Keskeiset asiat
- Palvelintila = täysin automaattinen, yksinkertainen ja nopea, ei välivaiheiden ohjausta
- Asiakastila = vastaanotat luovutustapahtumat ja päätät, mitä teet
- Asiakastila mahdollistaa validoinnin, lokituksen, ehdollisen reityksen ja virheenkäsittelyn
- Useimmissa tapauksissa palvelintila riittää – vaihda asiakastilaan, kun tarvitset ohjausta
- Molemmat tilat tukevat samoja agenttiketjuja; vain ohjaus eroaa