Salt la conținutul principal
Română— Alege o limbă
Meniu

Bune practici și pașii următori

Lecția 18 din 18 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Ce ați parcurs
  2. Proiectarea unor agenți rezistenți
  3. Gestionarea erorilor
  4. Observarea a ceea ce se întâmplă
  5. Testarea rutării
  6. Arhitectura de referință
  7. Încotro mai departe
  8. Puncte cheie
  9. Testați-vă cunoștințele

Ce ați parcurs

Ați parcurs întregul API Mistral Agents. Să facem un rezumat înainte de a intra în practicile de producție, deoarece fiecare parte a acestui curs se bazează pe cea precedentă.

Primele trei lecții au pus bazele: un agent AI este un sistem autonom cu o buclă de percepție-acțiune; API-ul se sprijină pe trei obiecte—Agent, Conversation și Entry; iar ceea ce separă un agent de un chatbot este persistența, instrumentele și transferurile de control (handoffs). Lecțiile 4 până la 7 au făcut aceste obiecte utilizabile: crearea și configurarea agenților cu client.beta.agents.create(), menținerea conversațiilor persistente cu conversations.start() și conversations.append(), și utilizarea modului direct fără un agent atunci când creați prototipuri și persistența nu aduce valoare.

Lecțiile 8 până la 11 au adăugat capacități. web_search vă oferă acces la informații curente cu citări automate; code_interpreter rulează Python într-un mediu izolat (sandbox), oferind agentului rezultate exacte acolo unde modelul singur ar aproxima; image_generation produce elemente vizuale din prompturi text; document_library aduce RAG integrat pentru propriile dumneavoastră documente. Lecțiile 12 până la 16 au arătat apoi mai mulți agenți lucrând împreună: transferurile de control mută comanda de la un agent la altul, arhitectura de referință asociază un router central cu specialiști, modul server automatizează acolo unde modul client vă menține în buclă, iar înlănțuirea nelimitată se descompune în modele liniare, de tip stea și hibride. În final, Lecția 17 a încheiat totul cu garduri de siguranță (guardrails), principiul privilegiului minim și moderarea upstream.

Proiectarea unor agenți rezistenți

O singură propoziție surprinde întregul curs: un agent, o responsabilitate, o descriere care spune când să fie apelat. Contrastul de mai jos face diferența tangibilă.

# BINE — agent specializat cu descriere precisă
agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="invoice-processor",
    description="Processes invoices: extracts amounts, dates, vendors.",
    instructions="Extract invoice information into structured JSON.",
    tools=[{"type": "document_library", "library_ids": [invoices_lib.id]}]
)

# RĂU — agent generic, vag
agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="helper",
    description="A helpful agent.",
    tools=[{"type": "web_search"}, {"type": "code_interpreter"}, {"type": "image_generation"}]
)

Al doilea agent va eșua în două moduri simultan. Niciun router nu va ști când să-i transfere o cerere, deoarece „un agent util“ nu descrie nicio situație. Iar când este totuși apelat, cele trei instrumente ale sale îl lasă liber să caute pe web ceva ce ar fi trebuit să calculeze sau să ilustreze ceva ce i s-a cerut să analizeze.

Gestionarea erorilor

Apelurile de rețea eșuează mai devreme sau mai târziu. O reîncercare cu backoff exponențial absoarbe incidentele tranzitorii fără a transforma o încetinire momentană într-o pană vizibilă.

import time

def safe_conversation(agent_id, query, max_retries=3):
    """Conversation with error handling and retry."""
    for attempt in range(max_retries):
        try:
            response = client.beta.conversations.start(
                agent_id=agent_id,
                inputs=query
            )
            return response
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # Exponential backoff
    return None

Backoff-ul exponențial—o secundă, apoi două, apoi patru—distinge o reîncercare civilizată de bombardarea unui serviciu care deja se chinuie. Rețineți, de asemenea, că ultima încercare rearuncă excepția în loc să returneze None: apelantul dumneavoastră trebuie să știe că operațiunea a eșuat.

Observarea a ceea ce se întâmplă

În producție, un flux de lucru multi-agent pe care nu îl puteți observa devine imposibil de depanat. Modul client vă oferă exact cârligele (hooks) de care aveți nevoie.

import logging
import time

logger = logging.getLogger("agents")

def monitored_conversation(agent_id, query):
    """Conversation with monitoring."""
    start = time.time()

    response = client.beta.conversations.start(
        agent_id=agent_id,
        inputs=query,
        handoff_execution="client"
    )

    handoff_count = 0
    tool_count = 0

    for entry in response.outputs:
        if entry.type == "agent.handoff":
            handoff_count += 1
            logger.info(f"Handoff #{handoff_count}: → {entry.next_agent_id}")
        elif entry.type == "tool.execution":
            tool_count += 1
            logger.info(f"Tool #{tool_count}: {entry.tool_name}")

    duration = time.time() - start
    logger.info(f"Finished in {duration:.1f}s — {handoff_count} handoffs, {tool_count} tools")

    return response

Acei doi contori valorează mai mult decât sugerează simplitatea lor: o abatere în numărul mediu de transferuri semnalează un router care ezită; un vârf în apelurile de instrumente indică interogări costisitoare.

Controlul costurilor se reduce apoi la decizii concrete. Monitorizați tokenii per conversație, deoarece aceea este unitatea reală de facturare. Utilizați mistral-medium-latest oriunde mistral-large-latest nu aduce nimic—primul nivel de suport este un exemplu clasic. Limitați max_tokens în completion_args pentru a evita răspunsurile interminabile la întrebări simple și dezactivați stocarea cu store=False atunci când persistența nu este necesară.

Testarea rutării

Testați un sistem multi-agent ca pe orice centrală telefonică: introduceți cazuri pentru care cunoașteți destinația așteptată și verificați unde ajung.

def test_agent_routing():
    """Verifies that the router distributes correctly."""
    test_cases = [
        ("What is the price of Bitcoin?", "web-search-agent"),
        ("Calculate 25 * 48", "calculator-agent"),
        ("Summarize this document", "doc-agent"),
    ]

    for query, expected_agent_name in test_cases:
        response = client.beta.conversations.start(
            agent_id=router.id,
            inputs=query,
            handoff_execution="client"
        )

        for entry in response.outputs:
            if entry.type == "agent.handoff":
                target = client.beta.agents.get(agent_id=entry.next_agent_id)
                assert target.name == expected_agent_name, \
                    f"Incorrect routing for '{ query}': {target.name} instead of {expected_agent_name}"

Construiți această suită de teste în timp: fiecare cerere dirijată greșit pe care o prindeți în producție devine o altă linie în test_cases, și veți ști că rescrierea unei descrieri repară cazul vizat fără a strica altul.

Arhitectura de referință

Pentru un proiect de producție, iată o arhitectură recomandată:

Application
    │
    ▼
Moderator Agent (filters requests)
    │
    ▼
Router Agent (distributes to specialists)
    ├── Search Agent (web_search)
    ├── Analysis Agent (code_interpreter)
    ├── Documents Agent (document_library)
    └── Creation Agent (image_generation)
    │
    ▼
Logging + Monitoring + Alerting

Aceasta reunește totul din acest curs: moderatorul filtrează înainte de orice execuție, routerul direcționează fără a răspunde vreodată el însuși, fiecare specialist deține un singur instrument și o singură responsabilitate, iar observarea învelește întregul sistem.

Încotro mai departe

Patru direcții extind ceea ce puteți face acum. Function calling vă permite să construiți propriile instrumente personalizate dincolo de cele încorporate: apelați un API de afaceri, interogați o bază de date, declanșați un serviciu intern. MCP Servers integrează Model Context Protocol, care standardizează modul în care sunt expuse instrumentele. Structured outputs forțează răspunsurile într-o schemă JSON, ceea ce schimbă totul atunci când ieșirea unui agent alimentează un alt sistem și nu un cititor uman. În final, streaming returnează răspunsurile în timp real în loc de un singur bloc—decisiv în lanțurile lungi, unde așteptarea tăcută devine inconfortabilă.

Trei resurse însoțesc acest pas următor: documentația oficială la docs.mistral.ai/agents, caietele de rețete (cookbooks) Mistral care oferă exemple complete de implementare și Referința API care documentează fiecare endpoint în detaliu.

Puncte cheie

  • Specializați agenții—un agent = o responsabilitate
  • Monitorizați—înregistrați fiecare transfer și execuție de instrument
  • Testați—validați rutarea și răspunsurile fiecărui agent
  • Securizați—garduri de siguranță, privilegiu minim, moderare upstream
  • Optimizați costurile—model dimensionat corect, max_tokens, store=False când este posibil
  • Mistral Agents sunt în versiune beta—țineți pasul cu modificările API

Testați-vă cunoștințele

Agenți, instrumente încorporate, transferuri: mai are API-ul Agents puncte moarte?

1. Când este necesar un agent și când este suficient un chatbot?

Răspuns: Un agent este justificat când aveți nevoie de instrumente, persistență și decizii în mai mulți pași; pentru întrebări și răspunsuri simple, o conversație standard este suficientă—arhitectura urmează nevoia.

2. Ce gestionează conversațiile persistente în API-ul Agents?

Răspuns: Istoricul din partea Mistral: continuați o conversație prin ID-ul său fără a retrimite întregul context—starea devine un serviciu.

3. Enumerați instrumentele încorporate disponibile și utilizarea lor.

Răspuns: web_search (informații în timp real), code_interpreter (rularea Python), image_generation (crearea de imagini), document_library (întrebări și răspunsuri pe fișierele dumneavoastră)—capacități gata de utilizare, fără implementare necesară.

4. Cum funcționează un sistem multi-agent cu transferuri?

Răspuns: Un router califică cererea și o transmite agentului specialist competent; fiecare agent rămâne simplu, orchestrarea asigură acoperirea—iar transferurile se înlănțuie în profunzime.

5. Cum securizați agenții în producție?

Răspuns: Cu garduri de siguranță pe intrări/ieșiri, instrumente cu scop restrâns, trasabilitatea acțiunilor și validare umană pentru deciziile cu miză mare—autonomia se câștigă prin control.

Agenți specializați, instrumente încorporate, rutare, garduri de siguranță: arhitectura completă încap în patru cuvinte—iar acest curs v-a făcut să construiți fiecare dintre ele.