Crearea unui Agent cu API-ul Python
Pe această pagină
Primul dumneavoastră Agent Mistral
Cele trei lecții anterioare au stabilit vocabularul de bază; această lecție vă pune mâinile pe tastatură. Veți crea un agent prin intermediul API-ului Python, îmbogățindu-l progresiv cu instrucțiuni, parametri de generare și instrumente, pentru a lansa apoi o conversație cu acesta. Progresia este intenționat incrementală: fiecare adăugire modifică un comportament observabil, arătându-vă de ce aceeași metodă create() poate produce fie un asistent generic, fie un expert cu un stil strict definit.
Condiții prealabile
Instalarea necesită doi pași. În primul rând, SDK-ul oficial.
pip install mistralai
În continuare, faceți cheia API disponibilă în mediul de execuție, în loc să o codificați direct în cod. Commit-ul accidental al unei chei într-un repository reprezintă primul incident de securitate pentru orice proiect LLM.
export MISTRAL_API_KEY="your-api-key"
Apoi, construiți clientul într-o singură linie. Acest obiect client servește drept punct de intrare pentru restul lecției.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Crearea unui Agent Minimal
Metoda client.beta.agents.create() acceptă trei parametri obligatorii și câțiva opționali. Să începem cu strictul necesar.
agent = client.beta.agents.create(
model="mistral-medium-latest",
name="Simple Assistant",
description="A conversational agent with persistent state."
)
print(f"Agent created: {agent.id}")
Acest agent este minimalist: fără instrucțiuni specifice, fără instrumente, fără garduri de siguranță (guardrails). Se comportă ca un endpoint Chat Completions îmbunătățit, cu persistență. Rețineți identificatorul returnat în agent.id: acesta este ceea ce stocați în partea de aplicație, deoarece este singura referință stabilă la această configurație.
Definirea Comportamentului prin Instrucțiuni
Instrucțiunile acționează ca promptul de sistem și sunt pârghia principală pentru controlul comportamentului. Exemplul de mai jos transformă un asistent generic într-un expert juridic al cărui domeniu, format și limite sunt delimitate explicit.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Legal Expert",
description="Agent specialized in French business law.",
instructions="""You are an expert in French business law.
Rules:
- Always respond in French
- Cite relevant legal articles
- Specify when a question requires a lawyer's opinion
- Structure your responses with headings and lists
- Never give definitive legal advice"""
)
Observați structura acestui prompt: o definiție a rolului la început, urmată de reguli numerotate. Această organizare secțională ajută modelul să prioritizeze constrângerile. Fiți specifici privind rolul, tonul și limitele, în loc să scrieți simplu „fiți util“. Mai presus de toate, anticipați cazurile limită—ce ar trebui să facă agentul dacă întrebarea iese din domeniul său de competență? Linia privind solicitarea opiniei unui avocat abordează exact acest aspect. În final, tratați instrucțiunile ca pe cod: le veți testa și revizui de mai multe ori înainte de a produce comportamentul așteptat.
Controlul Generării
Parametrii completion_args configurează sampler-ul, adică modul în care modelul își alege cuvintele. Un agent însărcinat cu reformularea faptelor nu are nevoie de aceeași libertate ca un agent de brainstorming.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Precise Agent",
description="Agent with controlled generation parameters.",
instructions="Respond factually and concisely.",
completion_args={
"temperature": 0.2, # Less creativity, more precision
"top_p": 0.9, # Probability nucleus
"max_tokens": 2048 # Response length limit
}
)
temperature— Variază de la 0.0 (determinist) la 1.0 (creativ). Pentru sarcini factuale, preferați 0.1–0.3.top_p— Filtrare prin probabilitate cumulativă. 0.9 este o valoare implicită bună.max_tokens— Limită strictă asupra tokenilor de ieșire.
Echiparea Agentului cu Instrumente
Un agent devine cu adevărat autonom atunci când poate acționa dincolo de text. Configurația următoare îi oferă atât acces la web, cât și executarea de cod: confruntat cu o întrebare care compară ratele actuale, va prelua valorile și va calcula rezultatul fără intervenția dumneavoastră.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Research Agent",
description="Agent with web search and code execution.",
instructions="Use web search for current information and code for calculations.",
tools=[
{"type": "web_search"},
{"type": "code_interpreter"}
],
completion_args={"temperature": 0.3, "top_p": 0.95}
)
Instrumentele disponibile includ: web_search, web_search_premium, code_interpreter, image_generation, document_library.
Gestionarea Ciclului de Viață al Agentului
Agenții dumneavoastră sunt resurse persistente pe partea Mistral și îi veți administra ca pe orice altă resursă: îi găsiți, îi modificați, îi ștergeți. Listarea este deosebit de utilă în timpul dezvoltării, unde ajungeți rapid să aveți zeci de agenți de test ale căror ID-uri le-ați pierdut.
# List all your agents
agents = client.beta.agents.list()
for a in agents.data:
print(f"{a.name} ({a.id})")
# Retrieve an agent by its ID
agent = client.beta.agents.get(agent_id="ag-xxxxxxxx")
Actualizările sunt parțiale: doar câmpurile furnizate sunt modificate; celelalte rămân așa cum sunt. Acest lucru vă permite să rafinați instrucțiunile în producție fără a redeclara întreaga configurație.
agent = client.beta.agents.update(
agent_id=agent.id,
instructions="New updated instructions.",
tools=[{"type": "web_search"}, {"type": "code_interpreter"}]
)
Ștergerea, însă, este permanentă.
client.beta.agents.delete(agent_id=agent.id)
Exemplu Complet
Să reunim totul într-un agent pe deplin funcțional: creare, conversație și citirea răspunsului. Puteți utiliza acest script ca atare; schimbați doar numele și instrucțiunile, iar în câteva minute veți avea propriul analist operațional.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Create the agent
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Tech Analyst",
description="Analyzes technology trends with web sources.",
instructions="""You are a technology analyst.
- Use web search for recent data
- Always cite your sources
- Structure your analyses into key points""",
tools=[{"type": "web_search"}],
completion_args={"temperature": 0.3}
)
# Start a conversation
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="What are the latest advancements in agentic AI in 2026?"
)
# Display the response
for entry in response.outputs:
if hasattr(entry, "content"):
print(entry.content)
Bucla finală merită o atenție deosebită: aceasta iterează peste response.outputs în loc să citească un singur câmp, deoarece un agent echipat cu instrumente produce mai multe intrări—execuția căutării, apoi textul. Acesta este punctul cheie de urmărit în lecția următoare.
Puncte cheie
client.beta.agents.create()creează un agent cu model, nume și descriere (obligatorii)- Instrucțiunile definesc comportamentul—aceasta este pârghia principală
completion_argscontrolează generarea (temperature, top_p, max_tokens)- Un agent poate avea multiple instrumente activate simultan
- Agenții sunt configurații reutilizabile, nu instanțe de conversație