Parhaat käytännöt ja seuraavat askeleet
Tällä sivulla
Mitä olet oppinut
Olet käynyt läpi koko Mistral Agents API:n. Kertaus ennen tuotantokäytäntöihin siirtymistä on paikallaan, sillä tämän kurssin jokainen osa rakentuu edellisen päälle.
Kolme ensimmäistä oppituntia loivat perustan: tekoälyagentti on autonominen järjestelmä, jossa havainto ja toiminta muodostavat silmukan; API nojaa kolmeen objektiin – Agent, Conversation ja Entry; ja agentin erottaa chatbotista pysyvyys, työkalut sekä vastuun siirrot (handoffs). Oppitunnit 4–7 tekivät näistä objekteista käyttökelpoisia: agenttien luominen ja konfigurointi komennolla client.beta.agents.create(), pysyvien keskustelujen ylläpito komennoilla conversations.start() ja conversations.append(), sekä suoran tilan käyttö ilman agenttia prototyyppivaiheessa, jolloin pysyvyydestä ei ole hyötyä.
Oppitunnit 8–11 lisäsivät ominaisuuksia. web_search tarjoaa pääsyn ajantasaiseen tietoon automaattisilla lähdeviitteillä; code_interpreter suorittaa Python-koodia hiekkalaatikossa, jolloin agentti saa tarkkoja tuloksia tilanteissa, joissa malli yksinään vain arvioisi niitä; image_generation tuottaa visuaalista sisältöä tekstikehotteista; document_library tuo integroidun RAG:n omiin dokumentteihisi. Oppitunnit 12–16 näyttivät sitten, miten useat agentit toimivat yhdessä: vastuun siirrot (handoffs) siirtävät kontrollin agentilta toiselle, viitearkkitehtuuri yhdistää keskeisen reitittimen erikoisagentteihin, palvelintila automatisoi prosessin kun taas asiakastila pitää sinut silmukassa, ja rajaton ketjutus jakautuu lineaarisiin, tähti- ja hybrideihin malleihin. Lopuksi oppitunti 17 kokosi kaiken yhteen suojakaiteiden, vähäisimmän oikeuden periaatteen ja ylävirran moderoinnin kautta.
Agenttien suunnittelu kestävyyttä varten
Yksi lause tiivistää koko kurssin: yksi agentti, yksi vastuualue, yksi kuvaus, joka kertoo milloin sitä tulee kutsua. Alla oleva vertailu tekee erosta konkreettisen.
# HYVÄ — erikoistunut agentti tarkalla kuvauksella
agent = client.beta.agents.create(
model="mistral-large-latest",
name="invoice-processor",
description="Processes invoices: extracts amounts, dates, vendors.",
instructions="Extract invoice information into structured JSON.",
tools=[{"type": "document_library", "library_ids": [invoices_lib.id]}]
)
# HUONO — yleinen, epämääräinen agentti
agent = client.beta.agents.create(
model="mistral-large-latest",
name="helper",
description="A helpful agent.",
tools=[{"type": "web_search"}, {"type": "code_interpreter"}, {"type": "image_generation"}]
)
Toinen agentti epäonnistuu kahdella tavalla samanaikaisesti. Mikään reititin ei tiedä milloin sille tulisi ohjata pyyntö, koska “avulias agentti” ei kuvaile mitään tiettyä tilannetta. Ja kun sitä lopulta kutsutaan, sen kolme työkalua antavat sille vapauden etsiä verkosta jotain, jonka sen olisi pitänyt laskea, tai kuvittaa jotain, jota sitä pyydettiin analysoimaan.
Virheiden käsittely
Verkkopyynnöt epäonnistuvat ennemmin tai myöhemmin. Yritä uudelleen eksponentiaalisella viiveellä (exponential backoff) absorboidaksesi ohimenevät häiriöt muuttamatta hetkellistä hidastumista näkyväksi katkokseksi.
import time
def safe_conversation(agent_id, query, max_retries=3):
"""Keskustelu virheenkäsittelyllä ja uudelleenyrityksellä."""
for attempt in range(max_retries):
try:
response = client.beta.conversations.start(
agent_id=agent_id,
inputs=query
)
return response
except Exception as e:
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt) # Exponential backoff
return None
Eksponentiaalinen viive – yksi sekunti, sitten kaksi, sitten neljä – erottaa kohteliaan uudelleenyrityksen palvelun pommituksesta, joka jo kamppailee. Huomaa myös, että viimeinen yritys heittää poikkeuksen uudelleen sen sijaan, että palauttaisi None: kutsujan on tiedettävä, että operaatio epäonnistui.
Tilanteen seuraaminen
Tuotannossa moniagenttinen työnkulku, jota et voi havainnoida, muuttuu mahdottomaksi vianetsiä. Asiakastila antaa juuri ne koukut, joita tarvitset.
import logging
import time
logger = logging.getLogger("agents")
def monitored_conversation(agent_id, query):
"""Keskustelu valvonnalla."""
start = time.time()
response = client.beta.conversations.start(
agent_id=agent_id,
inputs=query,
handoff_execution="client"
)
handoff_count = 0
tool_count = 0
for entry in response.outputs:
if entry.type == "agent.handoff":
handoff_count += 1
logger.info(f"Handoff #{handoff_count}: → {entry.next_agent_id}")
elif entry.type == "tool.execution":
tool_count += 1
logger.info(f"Tool #{tool_count}: {entry.tool_name}")
duration = time.time() - start
logger.info(f"Finished in {duration:.1f}s — {handoff_count} handoffs, {tool_count} tools")
return response
Nämä kaksi laskuria ovat arvokkaampia kuin niiden yksinkertaisuus antaa ymmärtää: keskimääräisen vastuunsiirtojen määrän muutos kertoo reitittimen epäröinnistä; työkalukutsujen piikki viittaa kalliisiin kyselyihin.
Kustannusten hallinta tiivistyy sitten konkreettisiin päätöksiin. Seuraa tokenien määrää keskustelua kohden, sillä se on todellinen laskutusyksikkö. Käytä mistral-medium-latest:ia aina kun mistral-large-latest ei tuo lisäarvoa – ensimmäisen tason tuki on tästä oppikirjaesimerkki. Aseta max_tokens-raja completion_args:iin välttääksesi loputtomat vastaukset yksinkertaisiin kysymyksiin, ja poista tallennus käytöstä asetuksella store=False, kun pysyvyyttä ei tarvita.
Reitityksen testaaminen
Testaa moniagenttista järjestelmää kuin mitä tahansa kytkinlautaa: syötä sille tapauksia, joiden odotettu kohde on tiedossa, ja varmista mihin ne päätyvät.
def test_agent_routing():
"""Varmistaa, että reititin jakaa pyynnöt oikein."""
test_cases = [
("What is the price of Bitcoin?", "web-search-agent"),
("Calculate 25 * 48", "calculator-agent"),
("Summarize this document", "doc-agent"),
]
for query, expected_agent_name in test_cases:
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 = client.beta.agents.get(agent_id=entry.next_agent_id)
assert target.name == expected_agent_name, \
f"Incorrect routing for '{ query}': {target.name} instead of {expected_agent_name}"
Rakenna tätä testisarjaa ajan myötä: jokainen tuotannossa kiinni saatu väärin reititetty pyyntö muuttuu uudeksi riviksi test_cases:iin, ja tiedät, että kuvauksen uudelleenkirjoittaminen korjaa kohdistetun tapauksen rikkomatta toista.
Viitearkkitehtuuri
Tuotantoprojektia varten tässä on suositeltu arkkitehtuuri:
Application
│
▼
Moderator Agent (filters requests)
│
▼
Router Agent (distributes to specialists)
├── Search Agent (web_search)
├── Analysis Agent (code_interpreter)
├── Documents Agent (document_library)
└── Creation Agent (image_generation)
│
▼
Logging + Monitoring + Alerting
Se tuo yhteen kaiken tästä kurssista: moderaattori suodattaa ennen mitään suorittamista, reititin ohjaa vastaamatta itse koskaan, jokainen erikoisagentti kantaa yhtä työkalua ja yhtä vastuuta, ja havainnointi kietoo koko järjestelmän.
Minne seuraavaksi
Neljä suuntaa laajentavat sitä, mitä voit tehdä nyt. Function calling antaa sinun rakentaa omia mukautettuja työkaluja sisäänrakennettujen lisäksi: kutsu liiketoiminta-APIa, kysy tietokannalta tai käynnistä sisäinen palvelu. MCP Servers integroivat Model Context Protocolin, joka standardoi tavan, jolla työkalut tehdään saataville. Structured outputs pakottavat vastaukset JSON-skeemaan, mikä muuttaa kaiken, kun agentin tuotos syötetään toiselle järjestelmälle ihmislukijan sijaan. Lopuksi streaming palauttaa vastaukset reaaliajassa yhden lohkon sijaan – ratkaisevan tärkeää pitkissä ketjuissa, joissa äänetön odotus muuttuu epämukavaksi.
Kolme resurssia accompanies tätä seuraavaa askelta: virallinen dokumentaatio osoitteessa docs.mistral.ai/agents, Mistral cookbooks, jotka tarjoavat täydellisiä toteutusesimerkkejä, sekä API Reference, joka dokumentoi jokaisen päätepisteen yksityiskohtaisesti.
Keskeiset asiat
- Erikoista agenttisi – yksi agentti = yksi vastuualue
- Valvo – lokita jokainen vastuunsiirto ja työkalun suoritus
- Testaa – validoi reititys ja kunkin agentin vastaukset
- Turvaa – suojakaiteet, vähäisin oikeuksin, ylävirran moderointi
- Optimoi kustannuksia – oikean kokoinen malli, max_tokens, store=False kun mahdollista
- Mistral Agents on beta-vaiheessa – pysy ajan tasalla API-muutoksista
Testaa tietämyksesi
Agentit, sisäänrakennetut työkalut, vastuunsiirrot: onko Agents API:ssa enää sokeita pisteitä?
1. Milloin agentti on välttämätön – ja milloin chatbot riittää?
Vastaus: Agentti on perusteltu, kun tarvitset työkaluja, pysyvyyttä ja monivaiheisia päätöksiä; yksinkertaiseen kysymys-vastaus-toimintaan tavallinen keskustelu riittää – arkkitehtuuri seuraa tarvetta.
2. Mitä pysyvät keskustelut Agents API:ssa hallinnoivat?
Vastaus: Historiaa Mistralin puolella: jatkat keskustelua sen ID:n avulla lähettämättä koko kontekstia uudelleen – tilasta tulee palvelu.
3. Listaa saatavilla olevat sisäänrakennetut työkalut ja niiden käyttötarkoitus.
Vastaus: web_search (reaaliaikainen tieto), code_interpreter (Pythonin suoritus), image_generation (kuvien luominen), document_library (kysymykset ja vastaukset tiedostoistasi) – valmiita ominaisuuksia, ei toteutusta vaadita.
4. Miten moniagenttinen järjestelmä vastuunsiirtoineen toimii?
Vastaus: Reititin luokittelee pyynnön ja välittää sen toimivaltaiselle erikoisagentille; jokainen agentti pysyy yksinkertaisena, orkestrointi tarjoaa kattavuuden – ja vastuunsiirrot ketjutuvat syvyyssuunnassa.
5. Miten turvaat agentit tuotannossa?
Vastaus: Syötteiden ja tulosteiden suojakaiteilla, kapeasti rajatuilla työkaluilla, toimintojen jäljitettävyydellä ja ihmisen validoinnilla kriittisissä päätöksissä – autonomia ansaitaan kontrollin kautta.
Erikoistuneet agentit, sisäänrakennetut työkalut, reititys, suojakaiteet: koko arkkitehtuuri mahtuu neljään sanaan – ja tämä kurssi sai sinut rakentamaan jokaisen niistä.