Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Suoritus palvelimella vs. asiakkaalla

Oppitunti 14 / 18 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Kaksi tapaa hallita luovutuksia
  2. Palvelintila, oletusarvo
  3. Asiakastila, kun haluat ohjausta
  4. Valinta kahden välillä
  5. Keskeiset asiat

Oppitunti päivitetty 3. marraskuuta 2026 perustuen mistralai SDK:n versioon 3.7.0 ja Mistralin Handoffs-dokumentaatioon: agent.handoff-merkintä tunnistaa kohdeagentin käyttämällä next_agent_id:tä (ei to_agent), eikä conversations.append hyväksy agent_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