Arhitectura API-ului Mistral Agents
Pe această pagină
Actualizat la 3 noiembrie 2026. Exemplul anterior complet de agent transmitea
guardrails={"enabled": True}, un format care nu există: parametrul oficial este o listă de configurațiimoderation_llm_v2. Intrareatool.executionexpune numele instrumentului înentry.name, nu înentry.tool_name, ceea ce genera anterior o eroareAttributeError. Surse: Agents & Conversations · Moderation & Guardrailing · SDKmistralai3.7.0.
Cele trei obiecte fundamentale
API-ul Mistral Agents se bazează pe trei obiecte care interacționează: Agent, Conversation și Entry. Majoritatea erorilor de design întâlnite la începutul unui proiect—recrearea unui agent pentru fiecare cerere, reutilizarea unui conversation_id expirat sau analizarea răspunsului care se blochează la o intrare neașteptată—provin din confuzia dintre aceste trei niveluri. Înțelegerea rolurilor și relațiilor lor este o condiție prealabilă pentru a scrie chiar și o singură linie de cod.
Obiectul Agent
Un Agent este un set de configurații care definește comportamentul modelului. Acesta nu conține date de conversație: este un șablon reutilizabil pe care îl creați o singură dată și la care pot face referință mii de conversații.
Crearea necesită cel puțin un model, un nume și o descriere.
agent = client.beta.agents.create(
model="mistral-large-latest", # Modelul LLM de utilizat
name="My Agent", # Identificator lizibil de om
description="Agent for financial analysis" # Descriere orientată spre sarcină
)
Parametrul model desemnează modelul care va alimenta agentul, ales dintre modelele de completare a chat-ului disponibile, cum ar fi mistral-medium-latest sau mistral-large-latest. Parametrul name este un identificator lizibil de om pe care îl utilizați pentru a găsi și a face referire la agent: într-un proiect cu douăzeci dintre ele, acesta este ceea ce vă scutește de a căuta prin jurnale pentru a afla care dintre ele răspunde clienților. Parametrul description, în schimb, este orientat spre sarcină și servește mai mult decât doar documentației interne—ajută modelul să înțeleagă rolul așteptat de la el, ceea ce explică formularea „agent pentru analiză financiară“ în loc de un vag „agentul numărul 3“.
Restul se configurează opțional, iar aici prinde viață personalitatea reală a agentului.
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— Promptul de sistem al agentului (definește personalitatea, regulile și stilul său)tools— Lista instrumentelor disponibile:web_search,web_search_premium,code_interpreter,image_generation,document_librarysau funcții personalizatecompletion_args— Parametrii eșantionatorului (temperature, top_p, max_tokens etc.)guardrails— O listă de configurații de moderare (moderation_llm_v2) aplicate mesajului de intrare al fiecărei conversații ale agentului; aici, jailbreaking-ul este blocat peste pragul de 0.2, iar categoriafinancialeste dezactivată (prag1), deoarece agentul este construit pentru a discuta despre finanțe. Detaliile se regăsesc în cursul Moderarea AI și securitatea cu Mistral.
În exemplul de mai sus, agentul financiar moștenește o cerință de citare a surselor din instrucțiunile sale, capacitatea de a verifica o cifră din instrumentele sale și o temperatură scăzută care limitează creativitatea acolo unde se așteaptă rigoare.
Obiectul Conversation
O Conversation reprezintă istoricul interacțiunilor dintre un utilizator și un agent—sau dintre un utilizator și un model singur. Conține mesaje, rezultate ale executării instrumentelor și evenimente de transfer (handoff).
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Analyze trends in the European AI market."
)
# Recuperați ID-ul conversației pentru a continua mai târziu
conversation_id = response.conversation_id
Comportamentul acestui obiect rezervă câteva surprize. Conversația este persistentă: istoricul este stocat pe partea Mistral, cu excepția cazului în care transmiteți store=False. Este independentă de agent, ceea ce înseamnă că o conversație poate exista perfect bine fără un agent, în modul direct de model. În final, este imutabilă: fiecare adăugare returnează un nou conversation_id, cel vechi rămânând accesibil. Acest ultim punct este cel mai surprinzător: dacă stocați ID-ul inițial în baza de date și îl reutilizați la a treia intervenție, veți reveni la contextul primului schimb.
Obiectul Entry
Un Entry este o acțiune individuală într-o conversație: unitatea atomică a istoricului. Când primiți un răspuns, câmpul outputs conține o listă de intrări al căror tip depinde de ceea ce a făcut agentul. O intrare message.output poartă un răspuns text de la agent, adică textul pe care interfața dumneavoastră îl va afișa. O intrare tool.execution poartă rezultatul executării unui instrument, cum ar fi codul sau o căutare pe web: scriptul lansat și ieșirea sa, sau paginile returnate de motor. O intrare agent.handoff semnalează un eveniment de transfer către un alt agent și, prin urmare, apare doar în scenarii multi-agent.
Un singur răspuns combină frecvent aceste tipuri. Dacă cereți unui agent dotat cu instrumente un calcul, veți primi execuția, apoi comentariul care o însoțește: codul dumneavoastră trebuie, prin urmare, să itereze prin această listă în loc să citească un singur câmp.
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}")
Relațiile dintre obiecte
Diagrama următoare rezumă articularea celor trei niveluri: o configurație reutilizabilă, un fir al istoricului și acțiuni unitare.
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)
Opțiuni pentru Conversation
Inițierea unei conversații acceptă setări care impactează atât conformitatea, cât și arhitectura dumneavoastră, iar este mai bine să le decideți dumneavoastră decât să le suferiți. Mai întâi, stocarea: store=False previne orice salvare pe partea Mistral, lucru pe care îl veți utiliza pentru a procesa date pe care politica internă vă interzice să le părăsească un server terț.
# Dezactivați stocarea în cloud
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Sensitive question",
store=False
)
A doua setare definește cine execută transferurile (handoffs). În modul server, valoarea implicită, Mistral înlănțuie transferurile de agenți fără intervenția dumneavoastră; în modul client, primiți evenimente de handoff și păstrați controlul pentru a le înregistra, filtra sau refuza.
# Modul server (implicit) — Mistral gestionează automat handoff-urile
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Complex request",
handoff_execution="server"
)
# Modul client — Primiți evenimente de handoff și decideți ce să faceți
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Complex request",
handoff_execution="client"
)
Puncte cheie
- Agent = configurație reutilizabilă (model, instructions, tools, guardrails)
- Conversation = istoric persistent stocat pe server, independent de agent
- Entry = acțiune unitară (mesaj, executare instrument, handoff)
- Conversațiile pot exista fără un agent (mod direct de model)
- Fiecare adăugare la o conversație creează un nou
conversation_id - Modul
store=Falseprevine stocarea pe partea Mistral