Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Server vs. Client Execution

Õppetund 14 / 18 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Kaks viisi üleminekute haldamiseks
  2. Serverirežiim, vaikeolek
  3. Client-režiim, kui soovid kontrolli
  4. Kahe vahel valimine
  5. Peamised punktid

Tund uuendatud 3. novembril 2026, tuginedes mistralai SDK versioonile 3.7.0 ja Mistrali Handoffs dokumentatsioonile: kirje agent.handoff määrab sihtagendi väljaga next_agent_id (mitte to_agent) ning conversations.append ei aktsepteeri parameetrit agent_id – vanem kood ei tööta. Sihtagendi töö jätkamine toimub siin uue vestluse kaudu, kellele annad edasi konteksti. Allikad: Handoffs · client-python.

Kaks viisi üleminekute haldamiseks

Kui agent annab juhtimise üle teisele agendile, pakub Mistral API kahte täitmise režiimi: server (automaatne) ja client (manuaalne). Seade koosneb ühest sõnast, kuid see määrab, kes tegelikult töövoogu juhib. Serverirežiimis delegeerid kogu orkestratsiooni Mistralile ja saad tulemuse kätte. Client-režiimis taastad kontrolli iga sammu vahel. Kõik muu – agendid, nende tööriistad, nende ülemineku sihtkohad – jääb täpselt samaks.

Serverirežiim, vaikeolek

response = client.beta.conversations.start(
    agent_id=router_agent.id,
    inputs="Analyze and calculate market trends.",
    handoff_execution="server"  # Vaikimisi – võib ära jätta
)

Voog on täielikult hallatud: ruuter saab päringu, otsustab üle anda uurimisagendile ja Mistral teostab ülemineku; uurimisagent teeb oma töö ja annab seejärel üle kalkulaatorile ning Mistral teostab ka selle; kalkulaator toodab tulemuse. Saad kätte lõpliku vastuse, millega kaasnevad kõik vahepealsed väljundid – näed seega, mis juhtus, kuid tagantjärele.

Sellel režiimil on kolm omadust, mis selgitavad, miks see on vaikeolek. See on lihtne, kuna sa ei pea oma poolel kirjutama mingit juhtimisloogikat. See on kiire, sest kogu ahel käivitub Mistralis ilma võrgu päringute vahetuseta igas edastusetapis. See on usaldusväärne, kuna veahaldus ja ajalõpud agentide vahel on sinu eest lahendatud.

Selle piirangud on täpne vastand. Sul puudub vahepealne kontroll: ülemineku käigus on võimatu seda valideerida või muuta. Kulud on läbipaistmatud selles mõttes, et kõik ahelas olevad agendid käivituvad ilma, et saaksid katkestada päringut, mis liigub ebavajalikus suunas. Ja sa ei saa sammude vahele lisada kohandatud loogikat – puudub peeneteraline logimine, valideerimine või äriotsused.

Client-režiim, kui soovid kontrolli

response = client.beta.conversations.start(
    agent_id=router_agent.id,
    inputs="Analyze the cloud market.",
    handoff_execution="client"
)

Ruuter saab päringu ja otsustab üle anda, täpselt nagu varem. Kuid ülemineku teostamise asemel saad sündmuse agent.handoff ja ahel peatub seal. Sinu otsustada on see taaskäivitada, kutsudes sihtagendi – see jätab sulle võimaluse valideerida, logida, konteksti rikastada või lihtsalt keelduda.

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

        # Valideeri ja anna seejärel üle sihtagendile koos kasuliku kontekstiga
        next_response = client.beta.conversations.start(
            agent_id=target_agent_id,
            inputs="Search for the latest tech news.",
        )

        # Töötle sihtagendi vastust
        for next_entry in next_response.outputs:
            print(f"{next_entry.type}: {next_entry.content}")

Üks punkt väärib tähelepanu: Mistrali dokumentatsioon kirjeldab client režiimi – kontroll naaseb sulle ülemineku hetkel – kuid ei paku meetodit, mille abil sihtagent sama vestlust jätkaks, ja conversations.append ei aktsepteeri parameetrit agent_id. Seetõttu alustab näide vestlust sihtagendiga, kellele edastad eksplitsiitselt vajaliku: algse päringu ja vajadusel kokkuvõtte seni tehtust. See on ka võimalus edastada ainult see, mida nad nägema peavad.

Ülalolev lõik käsitleb ainult üht edastust. Reaalne ahel ühendab mitut, mis eeldab tsüklit.

def execute_with_control(router_id, query):
    """Teostab mitme agendiga töövoogu kontrolliga igas etapis."""
    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}")

                # Siia saad lisada: valideerimise, logimise, mõõdikud
                response = client.beta.conversations.start(
                    agent_id=target,
                    inputs=query,  # algne päring, vajadusel rikastatud
                    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

Struktuur on nagu pumbal: seni kuni väljundites ilmneb üleminek, töötlead seda ja taaskäivitad; niipea kui tsükli iteratsioon ühtegi ei leia, on ahel lõppenud ja väljud kogutud sõnumitega. Kommentaar keskel märgib asukohta, mis õigustab kogu seda režiimi: just seal ja ainult seal sekkub sinu kood kahe agendi vahele.

Kahe vahel valimine

Serverirežiim katab standardse tootmise. Kui sinu töövoog on ennustatav, kui usaldad agente, mille oled kirjutanud, või kui teed prototüüpi ja tahad tulemusi kiiresti näha, on täielik automatiseerimine õige valik – ja juhtimistsükli kirjutamine oleks raisatud vaev.

Client-režiim on õigustatud niipea, kui ahelasse astub väline nõue. Inimese poolne valideerimine, kui operaator peab heaks kiitma ülemineku agendile, mis käivitab tundlikke toiminguid. Logimise ja auditeerimise vajadus, kui vastavusnõuded eeldavad iga sammu jälgimist oma identifikaatorite ja ajatemplitega. Tingimuslik marsruutimine, kui otsus sõltub ärireeglitest, mida mudel ei saa teada – kliendi staatus, kellaeg, kvoot. Piirang ehk kiiruse limiteerimine, kui soovid piirata päringu jaoks käivitatavate agentide arvu. Ja lõpuks varuplaan, kui ühe agendi tõrge peab käivitama midagi muud kui kasutajale kuvatava vea.

Siin on näide esimesest olukorrast, taandatud selle luustikuni.

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

Konsooli input teenib demonstratsioonina; rakenduses asendatakse see teatega operaatorile ja töövoogu taastamisega, kui vastus saabub. Põhimõte jääb samaks: üleminek toimub ainult siis, kui sinu kood selle käivitab.

Õige lähenemine on alustada serverirežiimis ja üle minna alles siis, kui konkreetne piirang seda nõuab. Üleminek client-režiimile „igaks juhuks“ paneb sind kohe maksma tsükli keerukuse ja võrgu päringute vahetuse eest kontrolli eest, mida sa veel ei kasuta.

Peamised punktid

  • Serverirežiim = täielikult automaatne, lihtne ja kiire, puudub vahepealne kontroll
  • Client-režiim = saad ülemineku sündmused ja otsustad, mida teha
  • Client-režiim võimaldab valideerimist, logimist, tingimuslikku marsruutimist ja veahaldust
  • Enamiku juhtumite puhul piisab serverirežiimist – lülitu client-režiimile, kui vajad kontrolli
  • Mõlemad režiimid toetavad samu agentide ahelaid; erineb ainult kontroll