Raționamentul în agenți și conversații
Pe această pagină
Lecție rescrisă la 2 noiembrie 2026 pentru Mistral Small 4 și Large 4. Documentația Mistral precizează că
reasoning_efforteste disponibil la punctele de terminare (endpoints) Agents și Conversations, în câmpulcompletion_args. Surse: Reasoning · Python SDK — Conversations.
Trei moduri de a apela un model de raționament
Lecțiile anterioare au utilizat API-ul Chat Completions: ați trimis întregul istoric la fiecare apel, iar reasoning_effort era inclus direct în cerere. Mistral oferă două alte interfețe: API-ul Agents, care salvează o configurație reutilizabilă (model, instrucțiuni, instrumente, parametri), și API-ul Conversations, care menține istoricul pe server. În aceste două API-uri, nu setați raționamentul la nivelul superior; îl imbricați în interiorul lui completion_args, alături de alți parametri de generare.
Un agent care raționează
Setarea nivelului de raționament în definiția agentului evită repetarea acestuia la fiecare apel și asigură că întreaga echipă utilizează aceeași configurare:
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
agent = client.beta.agents.create(
model="mistral-small-2603",
name="Financial Analyst",
instructions=(
"You analyze financial situations for SMEs. "
"End every response with a quantified recommendation and its assumptions."
),
completion_args={"reasoning_effort": "high"},
)
reponse = client.beta.conversations.start(
agent_id=agent.id,
inputs="Our working capital requirement has doubled in a year while revenue grew by 15%. What should we look at first?",
)
Citirea ieșirilor conversației
O conversație nu returnează choices; returnează o listă de intrări (outputs). Răspunsul modelului se află în intrările de tip message.output. La fel ca în cazul Chat Completions, conținutul este fie un șir de caractere, fie o listă de fragmente care pot include un ThinkChunk. Funcția separer din Lecția 3 funcționează exact ca înainte:
for entry in reponse.outputs:
if entry.type == "message.output":
reflexion, texte = separer(entry.content)
print(texte)
Alte intrări descriu ce s-a întâmplat în timpul turului de dialog, cum ar fi executarea unui instrument (tool.execution) sau un apel de funcție. Ignorați-le dacă vă interesează doar răspunsul final.
O conversație fără agent
Pentru sarcini unice, API-ul Conversations acceptă direct un model, fără configurarea prealabilă a unui agent. Serverul păstrează istoricul, iar dumneavoastră continuați schimbul cu conversations.append, ajustând nivelul de raționament pentru un tur specific dacă este necesar:
conv = client.beta.conversations.start(
model="mistral-large-4-0",
inputs="Propose a migration plan for a 2 TB PostgreSQL database with zero downtime.",
completion_args={"reasoning_effort": "high"},
)
suite = client.beta.conversations.append(
conversation_id=conv.conversation_id,
inputs="Summarize this plan in five steps for executive leadership.",
completion_args={"reasoning_effort": "low"}, # a summary doesn't need deep reflection
)
Acesta este un avantaj concret față de Chat Completions, unde documentația vă cere să redați mesajul complet al asistentului, inclusiv reflecția, la fiecare nou tur (Lecția 7). Cu API-ul Conversations, serverul păstrează istoricul; nu trebuie să îl retrimiteți la fiecare apel.
Raționament și instrumente
Un agent poate combina raționamentul și instrumentele: tools și completion_args sunt câmpuri independente la crearea unui agent. Astfel, un agent de analiză poate dispune de căutare web și raționament profund:
agent_veille = client.beta.agents.create(
model="mistral-small-2603",
name="Competitive Intelligence",
instructions="You compare competitor offers using cited public sources.",
tools=[{"type": "web_search"}],
completion_args={"reasoning_effort": "high"},
)
Fiți totuși atenți la costuri: reflecția și apelurile de instrumente se acumulează în factura pentru un singur tur de dialog.
Compararea celor trei abordări
| Criteriu | Chat Completions | Agents | Conversations |
|---|---|---|---|
| Unde se setează raționamentul | reasoning_effort în cerere | completion_args în agent | completion_args în start sau append |
| Istoric | Retrimis la fiecare apel, inclusiv reflecția | Gestionat de conversație | Păstrat pe server |
Instrumente integrate (web_search…) | Nu | Da | Da |
| Utilizare tipică | Apeluri unice, control total | Configurație partajată, reutilizabilă | Schimburi multi-tur |
Cele mai bune practici de integrare
Setați nivelul de raționament în agent atunci când sarcina este uniformă și pe fiecare tur atunci când variază: un tur inițial de analiză la high, urmat de tururi de reformulare la low sau none, în funcție de model. Verificați dacă valoarea este adecvată modelului agentului: Small 4 acceptă high și none; Large 4 acceptă low, medium și high. În final, înregistrați utilizarea tokenilor pe fiecare tur; este singura modalitate de a ști dacă raționamentul merită pentru cazul dumneavoastră de utilizare.
Puncte cheie
- În API-urile Agents și Conversations, transmiteți
reasoning_effortîn interiorul luicompletion_args - Răspunsurile sosesc în
outputs; textul se află în intrărilemessage.output, inclusiv reflecția - API-ul Conversations păstrează istoricul pe server: nu este nevoie să îl retrimiteți la fiecare tur
- Puteți modifica nivelul la fiecare tur cu
conversations.append - Un agent poate combina instrumente integrate și raționament, cu costul unei utilizări cumulative