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.
Î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
| Criteriu | Un apel | Workflow | Agent |
|---|---|---|---|
| Cât de variate sunt cererile | una singură, clară | câteva tipuri cunoscute | foarte variate, imprevizibile |
| Predictibilitate | maximă | mare: pașii sunt ficși | mai mică: drumul diferă |
| Cost pe cerere | 1 apel | 2-5 apeluri, știi câte | variabil, uneori 10+ apeluri |
| Risc (acțiuni) | nu acționează | acțiuni știute dinainte | poate alege acțiuni nedorite |
| Testare | un set de exemple | fiecare pas separat | evaluare 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
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
Reclamații: extrage datele, verifică comanda în baza de date, scrie răspunsul. Pașii sunt mereu aceiași.
Traducerea descrierilor de produse: un singur apel pe produs, eventual în batch.
„Nu merge VPN-ul”: uneori ajunge ghidul, alteori trebuie verificat contul sau deschis un tichet. Pașii depind de răspunsuri.
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.
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)) 