Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

Mistral Agents API Architecture

Nodarbība 3 no 18 Atjaunota 2026. gada 3. novembris Programmētājs
Šajā lapā
  1. Trīs fundamentālie objekti
  2. Objekts Agent (Aģents)
  3. Objekts Conversation (Saruna)
  4. Objekts Entry (Ieraksts)
  5. Objektu savstarpējās saistības
  6. Sarunu opcijas
  7. Galvenās atziņas

Atjaunināts 2026. gada 3. novembrī. Iepriekšējais pilnais aģenta piemērs nodeva guardrails={"enabled": True}, kas ir neeksistējošs formāts: oficiālais parametrs ir moderation_llm_v2 konfigurāciju saraksts. tool.execution ievade eksponē rīka nosaukumu laukā entry.name, nevis entry.tool_name, kas iepriekš izraisīja AttributeError. Avoti: Agents & Conversations · Moderation & Guardrailing · mistralai SDK 3.7.0.

Trīs fundamentālie objekti

Mistral Agents API balstās uz trīs mijiedarbojošiem objektiem: Agent (Aģents), Conversation (Saruna) un Entry (Ieraksts). Lielākā daļa kļūdu, ar kurām saskaras projekta sākumposmā — aģenta atkārtota izveide katram pieprasījumam, beiguša conversation_id atkārtota izmantošana vai atbildes parsēšana, kas avārijas režīmā apstājas negaidīta ieraksta dēļ — izriet no sajukuma starp šiem trim līmeņiem. To lomu un savstarpējo saistību izpratne ir priekšnosacījums, lai uzrakstītu pat vienu koda rindiņu.

Objekts Agent (Aģents)

Aģents ir konfigurācijas kopums, kas definē modeļa uzvedību. Tas nesatur sarunu datus: tas ir atkārtoti izmantojams šablons, ko izveido vienreiz un uz kuru var atsaukties tūkstošiem sarunu.

Izveidei obligāti nepieciešams vismaz modelis, nosaukums un apraksts.

agent = client.beta.agents.create(
    model="mistral-large-latest",        # Izmantojamais LLM modelis
    name="My Agent",                     # Cilvēkam lasāms identifikators
    description="Agent for financial analysis"  # Uz uzdevumu orientēts apraksts
)

Parametrs model norāda modeli, kas darbinās aģentu; to izvēlas no pieejamajām sarunu pabeigšanas modeļu versijām, piemēram, mistral-medium-latest vai mistral-large-latest. name ir cilvēkam lasāms identifikators, ko izmanto aģenta atrašanai un uz kuru atsaucas: projektā ar divdesmit šādiem elementiem tieši tas pasargā tevi no žurnālu pārcilāšanas, lai noskaidrotu, kurš no tiem atbild klientiem. Savukārt description ir orientēts uz uzdevumu un kalpo ne tikai iekšējai dokumentācijai — tas palīdz modelim saprast tam paredzēto lomu, kas izskaidro formulējumu “aģents finanšu analīzei”, nevis miglaino “aģents numur 3”.

Pārējo konfigurē pēc vajadzības, un tieši šeit veidojas aģenta patiesā personība.

agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="Complete Agent",
    description="Agent with all parameters",
    instructions="You are a finance expert. Always respond with sources.",
    tools=[
        {"type": "web_search"},
        {"type": "code_interpreter"}
    ],
    completion_args={"temperature": 0.3, "top_p": 0.95},
    guardrails=[
        {
            "block_on_error": True,
            "moderation_llm_v2": {
                "custom_category_thresholds": {"jailbreaking": 0.2, "financial": 1},
                "action": "block",
            },
        }
    ],
)
  • instructions — Aģenta sistēmas prompts (definē tā personību, noteikumus un stilu)
  • tools — Pieejamo rīku saraksts: web_search, web_search_premium, code_interpreter, image_generation, document_library vai pielāgotas funkcijas
  • completion_args — Paraugu ģenerēšanas parametri (temperature, top_p, max_tokens u.c.)
  • guardrails — Moderācijas konfigurāciju (moderation_llm_v2) saraksts, ko piemēro katra aģenta sarunas ienākošajam ziņojumam; šeit jailbreaking tiek bloķēts virs 0.2, bet kategorija financial ir atspējota (slieksnis 1), jo aģents ir izveidots finanšu jautājumu apspriešanai. Detalizēta informācija atrodama kursā AI Moderation and Security with Mistral.

Iepriekš minētajā piemērā finanšu aģents no savām instrukcijām manto prasību norādīt avotus, no saviem rīkiem — spēju pārbaudīt skaitļus, un zemu temperatūru, kas ierobežo radošumu tur, kur sagaida precizitāti.

Objekts Conversation (Saruna)

Saruna ir mijiedarbības vēsture starp lietotāju un aģentu — vai starp lietotāju un tikai modeli. Tā satur ziņojumus, rīku izpildes rezultātus un nodošanas (handoff) notikumus.

response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Analyze trends in the European AI market."
)

# Sarunas ID iegūšana turpināšanai vēlāk
conversation_id = response.conversation_id

Šī objekta uzvedībā slēpjas vairāki pārsteigumi. Saruna ir pastāvīga: vēsture tiek glabāta Mistral pusē, ja vien nenodod store=False. Tā ir neatkarīga no aģenta, kas nozīmē, ka saruna var pastāvēt arī bez aģenta, tiešā modeļa režīmā. Visbeidzot, tā ir nemainīga: katrs papildinājums atgriež jaunu conversation_id, kamēr vecais paliek pieejams. Šis pēdējais punkts ir vispārsteidzošākais: ja savā datubāzē saglabāsi sākotnējo ID un to izmantosi trešajā aprites solī, tu atgriezīsies pie pirmās apmaiņas konteksta.

Objekts Entry (Ieraksts)

Ieraksts ir individuāla darbība sarunas ietvaros: vēstures atomārā vienība. Saņemot atbildi, lauks outputs satur ierakstu sarakstu, kura veids ir atkarīgs no tā, ko aģents ir darījis. Ieraksts message.output nes aģenta teksta atbildi, proti, tekstu, ko parādīs tava saskarne. Ieraksts tool.execution nes rīka izpildes rezultātu, piemēram, kodu vai tīmekļa meklēšanu: palaisto skriptu un tā izvadi vai dzinēja atgrieztās lapas. Ieraksts agent.handoff signalizē par nodošanas notikumu citam aģentam, tāpēc tas parādās tikai multi-aģentu scenārijos.

Vienā atbildē šie veidi bieži sajaucas. Ja pajautāsi aģentam ar rīkiem veikt aprēķinu, tu saņemsi izpildi un tai sekojošo komentāru: tāpēc tavam kodam ir jāiterē cauri šim sarakstam, nevis jālasa viens vienīgs lauks.

response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Calculate the square root of 144"
)

for entry in response.outputs:
    print(f"Type: {entry.type}")
    if entry.type == "message.output":
        print(f"Message: {entry.content}")
    elif entry.type == "tool.execution":
        print(f"Tool: {entry.name}")

Objektu savstarpējās saistības

Tālāk redzamā diagramma apkopo šo trīs līmeņu savstarpējo saistību: atkārtoti izmantojama konfigurācija, vēstures pavediens un vienības darbības.

Agent (configuration)
  ├── model, instructions, tools, guardrails
  └── Can be referenced by N conversations

Conversation (history)
  ├── Linked to 0 or 1 Agent (optional)
  ├── Contains N ordered entries
  └── Each append creates a new conversation_id

Entry (unit action)
  ├── message.output (text response)
  ├── tool.execution (tool result)
  └── agent.handoff (agent transfer)

Sarunu opcijas

Sarunas uzsākšana pieņem iestatījumus, kas ietekmē gan tavu atbilstību prasībām, gan arhitektūru, un ir labāk tos izlemt pašam, nevis ļaut tiem notikt pašplūsmā. Vispirms par glabāšanu: store=False novērš jebkādu saglabāšanu Mistral pusē; to izmantosi, lai apstrādātu datus, kurus tava iekšējā politika aizliedz atstāt trešās puses serverī.

# Mākonia glabāšanas atspējošana
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Sensitive question",
    store=False
)

Otrais iestatījums definē, kurš izpilda nodošanas (handoffs). Režīmā server (noklusējuma vērtība) Mistral ķēdē aģentu nodošanas bez tavas iejaukšanās; režīmā client tu saņem handoff notikumus un saglabā kontroli, lai tos reģistrētu, filtrētu vai noraidītu.

# Servera režīms (noklusējums) — Mistral automātiski apstrādā nodošanas
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Complex request",
    handoff_execution="server"
)

# Klienta režīms — Tu saņem nodošanas notikumus un lemj, ko darīt
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Complex request",
    handoff_execution="client"
)

Galvenās atziņas

  • Agent = atkārtoti izmantojama konfigurācija (modelis, instrukcijas, rīki, guardrails)
  • Conversation = pastāvīga vēsture, kas glabāta serverī, neatkarīga no aģenta
  • Entry = vienības darbība (ziņojums, rīka izpilde, nodošana)
  • Sarunas var pastāvēt bez aģenta (tiešā modeļa režīms)
  • Katrs sarunas papildinājums rada jaunu conversation_id
  • Režīms store=False novērš glabāšanu Mistral pusē