...
← Curs Agenți AI și MCP: toate lecțiile
Lecția 4 · Ce este un agent AI

Agent, workflow sau un singur apel?

Nu orice problemă cere un agent. De multe ori un singur apel sau câțiva pași ficși, scriși de tine, sunt mai ieftini, mai rapizi și mai ușor de testat. În această lecție înveți să alegi nivelul potrivit și construiești un workflow în doi pași, cu o „poartă” verificată în cod.

Scara complexității

Gândește-te la trei niveluri. Un singur apel: trimiți textul, primești răspunsul (rezumi un email, clasifici o recenzie). Workflow: mai multe apeluri, dar ordinea lor o scrii tu în cod. Agent: modelul decide singur ce tool-uri folosește și de câte ori. Fiecare treaptă în sus aduce flexibilitate, dar și cost, latență și risc.

Un singur apelrezumă, traduce,clasifică un textWorkflowpașii îi scrii tu: lanț,rutare, paralelizareAgentmodelul alege pașiiși tool-urilecost, latență, riscpredictibil, ușor de testatflexibil la cereri variate
Scara complexității: urci o treaptă doar când treapta de jos nu mai rezolvă problema.
Regula de aur

Începi cu cel mai simplu lucru care merge. Echipa Anthropic, în ghidul „Building effective agents”, recomandă exact asta: multe aplicații reușite sunt workflow-uri simple, iar agenții se justifică atunci când pașii nu pot fi prevăzuți dinainte.

Cum alegi

CriteriuUn apelWorkflowAgent
Cât de variate sunt cererileuna singură, clarăcâteva tipuri cunoscutefoarte variate, imprevizibile
Predictibilitatemaximămare: pașii sunt ficșimai mică: drumul diferă
Cost pe cerere1 apel2-5 apeluri, știi câtevariabil, uneori 10+ apeluri
Risc (acțiuni)nu acționeazăacțiuni știute dinaintepoate alege acțiuni nedorite
Testareun set de exemplefiecare pas separatevaluare pe traiectorii (modulul 6)

Tiparele de workflow cele mai folosite: înlănțuirea (ieșirea unui pas e intrarea următorului), rutarea (un clasificator trimite cererea la handler-ul potrivit, lecția următoare) și paralelizarea (mai multe apeluri independente, ale căror rezultate le combini; o vezi în modulul 5).

Înlănțuirea: pasul 1 extrage datele

Un magazin online primește reclamații scrise liber. Pasul 1 transformă textul în date structurate: produs, problemă, număr de comandă. Folosești ieșirea JSON garantată (output_config cu json_schema, din cursul Aplicații AI), ca pasul 2 să primească mereu aceleași câmpuri.

import json
import re
import anthropic

MODEL = "claude-haiku-5-5"
client = anthropic.Anthropic()
JURNAL = []   # ce apeluri la model s-au făcut, în ordine


def apel(pas, **params):
    JURNAL.append(pas)
    return client.messages.create(model=MODEL, **params)


SCHEMA = {
    "type": "object",
    "properties": {"produs": {"type": "string"}, "problema": {"type": "string"},
                   "comanda": {"type": "string", "description": "numărul comenzii, de forma A-1234; gol dacă lipsește"}},
    "required": ["produs", "problema", "comanda"],
    "additionalProperties": False,
}


def extrage(text):
    """Pasul 1: din reclamația liberă scoate datele structurate."""
    r = apel("extrage", max_tokens=300, messages=[{"role": "user", "content": text}],
             system="Extragi datele unei reclamații pentru magazinul online Casa Bună.",
             output_config={"format": {"type": "json_schema", "schema": SCHEMA}})
    return json.loads(r.content[0].text)

RECLAMATII = [
    "Bună ziua, espressorul Mira primit cu comanda A-5521 nu încălzește apa deloc. Ce pot face?",
    "Aspiratorul cumpărat luna trecută face un zgomot ciudat și miroase a ars.",
]

date = extrage(RECLAMATII[1])          # reclamația aspiratorului
print(json.dumps(date, ensure_ascii=False, indent=1))
print("Apeluri:", JURNAL)
{
 "produs": "aspirator",
 "problema": "face zgomot și miroase a ars",
 "comanda": ""
}
Apeluri: ['extrage']

Reclamația aspiratorului nu are număr de comandă, iar modelul a lăsat câmpul gol, cum i-a cerut descrierea din schemă. Ce faci mai departe nu mai decide modelul, ci codul tău.

Poarta: o verificare în cod între pași

Poarta (gate) este o verificare deterministă între doi pași: dacă datele nu sunt bune, oprești lanțul și faci altceva (ceri clientului informația, trimiți la un om). E scrisă în Python, nu în prompt, deci merge de fiecare dată la fel și nu costă tokeni.

import re


def poarta(date):
    """Poarta dintre pași: o verificare în COD, nu în prompt."""
    return bool(re.fullmatch(r"A-\d{4}", date.get("comanda", "")))


print(poarta({"produs": "espressor", "comanda": "A-5521"}))
print(poarta({"produs": "aspirator", "comanda": ""}))
print(poarta({"produs": "frigider", "comanda": "5521"}))
True
False
False
Reclamațiatext liberApel 1extrage → JSONPoartaA-\d{4} ?Apel 2raspundedanuceri clientului numărulfără al doilea apelpașii sunt scriși de tine, în ordinea asta, mereu
Workflow-ul reclamațiilor: apelul 1 extrage JSON, poarta verifică numărul comenzii în cod, apelul 2 scrie răspunsul doar dacă poarta trece.

Avantajul se vede imediat: pentru reclamația fără comandă nu mai plătești al doilea apel, iar clientul primește un mesaj util în loc de un răspuns inventat despre o comandă inexistentă.

Greșeli frecvente

  • Construiești un agent pentru o sarcină cu pași ficși. Dacă știi dinainte că mereu extragi datele și apoi răspunzi, un workflow e mai ieftin și mai ușor de testat.
  • Pui poarta în prompt („dacă lipsește comanda, nu răspunde”). Modelul o va respecta de cele mai multe ori, dar nu mereu. Verificările care se pot scrie în cod se scriu în cod.
  • Pasul 2 primește tot textul inițial în loc de câmpurile extrase. Pierzi avantajul înlănțuirii: pasul 2 trebuie să lucreze pe date curate și verificate.
  • Citești JSON-ul fără schemă. Fără output_config cu json_schema, modelul poate adăuga text înainte de JSON și json.loads aruncă JSONDecodeError.

Exemple reale

MagazinWorkflow

Reclamații: extrage datele, verifică comanda în baza de date, scrie răspunsul. Pașii sunt mereu aceiași.

TraduceriUn apel

Traducerea descrierilor de produse: un singur apel pe produs, eventual în batch.

Helpdesk ITAgent

„Nu merge VPN-ul”: uneori ajunge ghidul, alteori trebuie verificat contul sau deschis un tichet. Pașii depind de răspunsuri.

Exercițiul tău

Completează workflow-ul reclamațiilor magazinului Casa Bună: poarta verifică numărul comenzii, iar pasul 2 scrie răspunsul doar pentru reclamațiile care trec de poartă. Funcția extrage (pasul 1) și apel (care ține jurnalul apelurilor) sunt în starter.

  • Scrie poarta(date): întoarce True doar dacă date["comanda"] are forma A-1234 (re.fullmatch(r"A-\d{4}", ...)).
  • Scrie raspunde(date): un apel apel("raspunde", ...) cu system-ul dat și un mesaj user care conține produsul, problema și numărul comenzii; întoarce textul.
  • În buclă: afișează Date: <JSON> (cu ensure_ascii=False), apoi Poarta: trece și Răspuns: ..., sau Poarta: oprit (lipsește numărul comenzii) și Către client: Vă rugăm să ne trimiteți numărul comenzii (de forma A-1234).
  • Ultima linie (Apeluri la model: ...) e deja în starter și arată ce apeluri s-au făcut cu adevărat.
Mesajul pentru pasul 2 poate fi f"Scrie răspunsul pentru client. Produs: {date['produs']}. Problema: {date['problema']}. Comanda: {date['comanda']}."

Soluția exercițiului

import json
import re
import anthropic

MODEL = "claude-haiku-5-5"
client = anthropic.Anthropic()
JURNAL = []   # ce apeluri la model s-au făcut, în ordine


def apel(pas, **params):
    JURNAL.append(pas)
    return client.messages.create(model=MODEL, **params)


SCHEMA = {
    "type": "object",
    "properties": {"produs": {"type": "string"}, "problema": {"type": "string"},
                   "comanda": {"type": "string", "description": "numărul comenzii, de forma A-1234; gol dacă lipsește"}},
    "required": ["produs", "problema", "comanda"],
    "additionalProperties": False,
}


def extrage(text):
    """Pasul 1: din reclamația liberă scoate datele structurate."""
    r = apel("extrage", max_tokens=300, messages=[{"role": "user", "content": text}],
             system="Extragi datele unei reclamații pentru magazinul online Casa Bună.",
             output_config={"format": {"type": "json_schema", "schema": SCHEMA}})
    return json.loads(r.content[0].text)

RECLAMATII = [
    "Bună ziua, espressorul Mira primit cu comanda A-5521 nu încălzește apa deloc. Ce pot face?",
    "Aspiratorul cumpărat luna trecută face un zgomot ciudat și miroase a ars.",
]


def poarta(date):
    return bool(re.fullmatch(r"A-\d{4}", date.get("comanda", "")))


def raspunde(date):
    cerere = (f"Scrie răspunsul pentru client. Produs: {date['produs']}. "
              f"Problema: {date['problema']}. Comanda: {date['comanda']}.")
    r = apel("raspunde", max_tokens=400, system="Ești echipa de relații cu clienții a magazinului Casa Bună.",
             messages=[{"role": "user", "content": cerere}])
    return r.content[0].text


for i, text in enumerate(RECLAMATII, 1):
    print(f"Reclamația {i}")
    date = extrage(text)
    print(f"Date: {json.dumps(date, ensure_ascii=False)}")
    if poarta(date):
        print("Poarta: trece")
        print(f"Răspuns: {raspunde(date)}")
    else:
        print("Poarta: oprit (lipsește numărul comenzii)")
        print("Către client: Vă rugăm să ne trimiteți numărul comenzii (de forma A-1234).")

print("Apeluri la model:", ", ".join(JURNAL))
Excelent! Continuă cu lecția următoare →
main.pyPython
ConsolăSe încarcă...
Mediul de lucru se încarcă. Poți citi lecția între timp.
Rulează codul cu butonul de sus sau cu Ctrl + Enter / Cmd + Enter.
Parcursul tău Ce este un agent AI Lecția 4 · Agent, workflow sau un singur apel?
Progres 0% 0 din 10
Lecția curentă 4 / 8 Ce este un agent ai