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

Luo erikoistuneita agentteja ja reititin

Oppitunti 13 / 18 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Teoriasta käytäntöön
  2. Vaihe 1: Luo erikoisagentit
  3. Vaihe 2: Luo reititinagentti
  4. Vaihe 3: Määritä siirtokohteet
  5. Vaihe 4: Aloita keskustelu
  6. Päävipu: kuvaus
  7. Täydellinen esimerkki
  8. Keskeiset asiat

Teoriasta käytäntöön

Edellisessä oppitunnissa esiteltiin siirtojen (handoffs) käsite. Nyt rakennat koko järjestelmän sen todellisessa rakennusjärjestyksessä: ensin erikoisagentit, sitten reititin, niiden välinen kytkentä ja lopuksi keskustelu, joka laittaa kaiken liikkeelle. Tämä järjestys ei ole mielivaltainen – reititin voi ohjata vain agenteille, jotka ovat jo olemassa.

Vaihe 1: Luo erikoisagentit

Jokainen agentti saa täsmällisen osaamisalueen eikä mitään muuta.

from mistralai.client import Mistral
from mistralai.client.models import CompletionArgs, ResponseFormat, JSONSchema
import os

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Verkkohakuagentti
web_agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="web-search-agent",
    description="Agentti, joka etsii tietoa verkosta.",
    instructions="Suorita tarkkoja verkkohakuja. Mainitse aina lähteesi.",
    tools=[{"type": "web_search"}]
)

# Rahoitusagentti
finance_agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="finance-agent",
    description="Rahoituskysymyksiin erikoistunut agentti.",
    instructions="""Olet rahoitusasiantuntija.
- Käytä numeerista dataa
- Selitä käsitteet selkeästi
- Merkitse riskit"""
)

# Laskinagentti
calculator_agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="calculator-agent",
    description="Agentti yksityiskohtaisia matemaattisia laskelmia varten.",
    instructions="Selitä jokainen laskun vaihe. Käytä kooditulkintaa monimutkaisiin laskelmiin.",
    tools=[{"type": "code_interpreter"}]
)

Näillä neljällä kentällä on hyvin erilaiset roolit, ja yksi ansaitsee erityistä huomiota. Kebab-case-muotoinen name on sinua varten: se näkyy lokeissasi ja testeissäsi, ja luettava nimi säästää sinua läpinäkymättömien tunnisteiden vertailulta. instructions-kenttä osoittaa mallille suunnan sen aloittaessa työnsä, joten sen on oltava toimialakohtainen – “merkitse riskit” tarkoittaa jotakin rahoitusagentille, kun taas “ole avulias” ei tarkoita kenellekään mitään. tools noudattavat tiukan välttämättömyyden periaatetta: yllä olevalla rahoitusagentilla ei ole työkaluja, koska se päättelee ilman niitä, ja työkalujen antaminen sille kutsuisi vain väärinkäyttöä. Lopuksi description ei ole dokumentaatiota: se on teksti, jonka reititin lukee päättääkseen, siirtääkö pyynnön tänne vai muualle.

Vaihe 2: Luo reititinagentti

Reittimellä ei ole työkaluja. Sen koko tehtävä on analysoida pyyntö ja valita vastaanottaja.

router_agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="router-agent",
    description="Reititinagentti, joka jakaa pyynnöt.",
    instructions="""Olet orkestroija.
Analysoi jokainen pyyntö ja siirrä se oikealle agentille:
- Online-dataa vaativat kysymykset → web-search-agent
- Rahoituskysymykset → finance-agent
- Laskelmat ja numeerinen analyysi → calculator-agent

Älä koskaan vastaa suoraan – siirrä aina eteenpäin."""
)

Viimeinen rivi estää järjestelmän romahtamisen. Ilman sitä suureen malliin perustuva reititin vastaisi kysymyksiin, jotka vaikuttavat sille helpoilta, ohittaisi erikoisagenttisi ja tuottaisi vastauksia ilman työkaluja, joita ne olisivat käyttäneet. Lopputuloksena on moniagenttiarkkitehtuuri, jossa puolet agenteista jää käyttämättä.

Vaihe 3: Määritä siirtokohteet

Nyt sinun on kerrottava reittimelle, mille agenteille se saa siirtää pyyntöjä.

router_agent = client.beta.agents.update(
    agent_id=router_agent.id,
    handoffs=[web_agent.id, finance_agent.id, calculator_agent.id]
)

handoffs-parametri ottaa vastaan listan agenttitunnisteista, ja reititin voi siirtää pyynnön mille tahansa niistä. Tämä ei ole varattu vain reittimelle: erikoisagentit voivat myös määrittää omat kohteensa.

# Rahoitusagentti voi siirtää verkkohakuun ja laskimeen
finance_agent = client.beta.agents.update(
    agent_id=finance_agent.id,
    handoffs=[web_agent.id, calculator_agent.id]
)

Ketju kuten reititin → rahoitus → verkkohaku → laskin tulee tällöin mahdolliseksi. Kun rahoitusagentti kohtaa kysymyksen, joka vaatii ajantasaista kurssia, se ei palaa reittimelle: se menee suoraan tarvitsemaansa erikoisagenttiin, aivan kuin konsultti soittaisi kollegalleen sen sijaan, että menisi takaisin vastaanottoon.

Vaihe 4: Aloita keskustelu

response = client.beta.conversations.start(
    agent_id=router_agent.id,
    inputs="Etsi EKP:n nykyinen ohjauskorko ja laske korkoa korolle 10 vuodelle 100 000 eurolle."
)

# Analysoi virtausta
for entry in response.outputs:
    if entry.type == "agent.handoff":
        print(f"[HANDOFF] → {entry.next_agent_id}")
    elif entry.type == "tool.execution":
        print(f"[TOOL] {entry.tool_name}")
    elif entry.type == "message.output":
        print(f"[RESPONSE] {entry.content[:200]}...")

Suorita tämä pyyntö ja tarkkaile jälkeä ennen kuin katsot vastausta. Sinun pitäisi nähdä kaksi siirtoa ja vähintään yksi työkalun suoritus; jos et näe yhtäkään, reittimesi vastasi itse, ja on aika kiristää sen ohjeistusta.

Päävipu: kuvaus

Kun reititys epäonnistuu, syyllinen on lähes aina kuvaus. Reititin ei tiedä aikomuksiasi; se lukee vain tämän tekstin jokaisesta ehdokasagentista.

# Huono – liian epämääräinen
description="Hyödyllinen agentti."

# Hyvä – reititin tietää, milloin siirtää
description="Agentti, joka etsii ajantasaista tietoa internetistä ja mainitsee lähteensä."

Kirjoita jokainen kuvaus vastauksena kysymykseen “missä tapauksessa minun pitäisi kutsua tätä agenttia?” sen sijaan, että tekisit yhteenvedon siitä, mitä se on. Toinen esimerkki nimeää tilanteen – ajantasainen tieto, internetissä – kun taas ensimmäinen jättää reittimen arvailemaan. Varmista myös, ettei mikään kuvauspari ole päällekkäinen: kaksi samankaltaisin termein kuvattua agenttia tuottaa epävakaa reititystä suorituksasta toiseen.

Täydellinen esimerkki

Tässä on tiivistetty versio, jossa handoffs välitetään suoraan reititintä luotaessa, koska erikoisagentit ovat jo olemassa siihen mennessä.

from mistralai.client import Mistral
import os

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# 1. Erikoisagentit
research = client.beta.agents.create(
    model="mistral-large-latest",
    name="research-agent",
    description="Verkkotietojen haku lähteineen.",
    tools=[{"type": "web_search"}]
)

analyst = client.beta.agents.create(
    model="mistral-large-latest",
    name="analyst-agent",
    description="Data-analyysi ja laskelmat Pythonilla.",
    tools=[{"type": "code_interpreter"}]
)

writer = client.beta.agents.create(
    model="mistral-large-latest",
    name="writer-agent",
    description="Rakenteisten ja ammattimaisten raporttien laatiminen.",
    instructions="Kirjoita selkeitä raportteja, joissa on johdanto, analyysi ja suositukset."
)

# 2. Reititin siirroilla
router = client.beta.agents.create(
    model="mistral-large-latest",
    name="router",
    description="Orkestroi monimutkaisia pyyntöjä.",
    instructions="Analysoi pyyntö ja siirrä se sopivalle erikoisagentille.",
    handoffs=[research.id, analyst.id, writer.id]
)

# 3. Käynnistys
response = client.beta.conversations.start(
    agent_id=router.id,
    inputs="Analysoi Euroopan pilvipalvelumarkkinoita vuonna 2026: koko, toimijat, trendit."
)

Keskeiset asiat

  • Luo erikoisagentteja, joilla on tarkat, tehtäväsuuntautuneet kuvaukset
  • Reititin käyttää kuvauksia valitakseen kohdeagentin
  • client.beta.agents.update(handoffs=[...]) määrittää siirtokohteet
  • Siirrot voivat olla sisäkkäisiä (agentti A → agentti B → agentti C)
  • Jokaisen agentin kuvaus on ensisijainen vipu reityksen laadulle