Cele patru piese ale unui agent: model, tool-uri, buclă, memorie
În lecția trecută agentul a mers din prima. Acum îl desfaci în bucăți: vezi ce rol are fiecare piesă și, mai ales, ce se strică atunci când lipsește. Cel mai des greșită este memoria, pentru că API-ul nu ține minte nimic între cereri.
Patru piese, un singur obiectiv
Un agent nu este un program magic, ci patru lucruri banale puse împreună. Modelul citește tot ce i-ai trimis și decide pasul următor. Tool-urile sunt funcțiile tale Python pe care modelul le poate cere. Bucla este codul care execută ce cere modelul și trimite rezultatul înapoi, până la răspunsul final. Memoria scurtă este lista mesaje pe care o trimiți, întreagă, la fiecare apel.
Gândește-te la un librar nou la tejghea. Mintea lui este modelul, calculatorul cu stocul și prețurile sunt tool-urile, obiceiul de a verifica până știe răspunsul este bucla, iar faptul că își amintește ce carte ai cerut acum un minut este memoria. Scoate oricare dintre ele și clientul pleacă nemulțumit.
Fără buclă: agentul se oprește la primul pas
Dacă trimiți o singură cerere, modelul îți răspunde că vrea un tool, iar programul se termină. Clientul nu primește nimic. Rulează exemplul și uită-te la stop_reason:
import anthropic
MODEL = "claude-haiku-5-5"
client = anthropic.Anthropic()
SYSTEM = "Ești asistentul librăriei Cărturia. Răspunzi scurt și verifici stocul și prețul doar cu tool-urile tale."
CARTI = {
"Enigma Otiliei": {"autor": "G. Călinescu", "stoc": 3, "pret": 45},
"Ion": {"autor": "L. Rebreanu", "stoc": 0, "pret": 39},
}
def cauta_carte(titlu):
c = CARTI.get(titlu)
if not c:
return f"Nu avem cartea {titlu}."
return f"{titlu} de {c['autor']}, {c['stoc']} exemplare în stoc"
def pret_carte(titlu):
c = CARTI.get(titlu)
return f"{c['pret']} lei" if c else f"Nu avem cartea {titlu}."
FUNCTII = {"cauta_carte": cauta_carte, "pret_carte": pret_carte}
TOOLS = [
{"name": "cauta_carte", "description": "Caută o carte după titlu și spune dacă e în stoc.",
"input_schema": {"type": "object", "properties": {"titlu": {"type": "string"}}, "required": ["titlu"]}},
{"name": "pret_carte", "description": "Prețul unei cărți, după titlu.",
"input_schema": {"type": "object", "properties": {"titlu": {"type": "string"}}, "required": ["titlu"]}},
]
def text_din(raspuns):
return " ".join(b.text for b in raspuns.content if b.type == "text")
# UN SINGUR apel, fără buclă
mesaje = [{"role": "user", "content": "Aveți romanul Enigma Otiliei?"}]
raspuns = client.messages.create(model=MODEL, max_tokens=500, system=SYSTEM, tools=TOOLS, messages=mesaje)
print("stop_reason:", raspuns.stop_reason)
print("Blocuri:", [b.type for b in raspuns.content])
print("Text pentru client:", repr(text_din(raspuns)))
stop_reason: tool_use Blocuri: ['tool_use'] Text pentru client: ''
Răspunsul conține doar blocul tool_use, fără text. Modelul a spus „vreau să rulez cauta_carte” și a așteptat rezultatul, dar nimeni nu i l-a trimis. Asta face bucla: execută cererea și continuă conversația până când stop_reason nu mai este tool_use.
Fără tool-uri: agentul inventează
Acum invers: bucla există, dar nu îi dai modelului tool-urile. El nu are de unde să afle stocul sau prețul, așa că răspunde din ce i se pare plauzibil:
import anthropic
MODEL = "claude-haiku-5-5"
client = anthropic.Anthropic()
SYSTEM = "Ești asistentul librăriei Cărturia. Răspunzi scurt și verifici stocul și prețul doar cu tool-urile tale."
CARTI = {
"Enigma Otiliei": {"autor": "G. Călinescu", "stoc": 3, "pret": 45},
"Ion": {"autor": "L. Rebreanu", "stoc": 0, "pret": 39},
}
def cauta_carte(titlu):
c = CARTI.get(titlu)
if not c:
return f"Nu avem cartea {titlu}."
return f"{titlu} de {c['autor']}, {c['stoc']} exemplare în stoc"
def pret_carte(titlu):
c = CARTI.get(titlu)
return f"{c['pret']} lei" if c else f"Nu avem cartea {titlu}."
FUNCTII = {"cauta_carte": cauta_carte, "pret_carte": pret_carte}
TOOLS = [
{"name": "cauta_carte", "description": "Caută o carte după titlu și spune dacă e în stoc.",
"input_schema": {"type": "object", "properties": {"titlu": {"type": "string"}}, "required": ["titlu"]}},
{"name": "pret_carte", "description": "Prețul unei cărți, după titlu.",
"input_schema": {"type": "object", "properties": {"titlu": {"type": "string"}}, "required": ["titlu"]}},
]
def text_din(raspuns):
return " ".join(b.text for b in raspuns.content if b.type == "text")
# bucla există, dar modelul nu are tool-uri: răspunde din ce „crede”
mesaje = [{"role": "user", "content": "Aveți romanul Enigma Otiliei?"}]
raspuns = client.messages.create(model=MODEL, max_tokens=500, system=SYSTEM, messages=mesaje)
print("Răspuns:", text_din(raspuns))
print("Prețul real din CARTI:", CARTI["Enigma Otiliei"]["pret"], "lei")
Răspuns: Da, sigur avem Enigma Otiliei, costă cam 30 de lei și o puteți ridica azi. Prețul real din CARTI: 45 lei
Un răspuns fluent nu înseamnă un răspuns corect. Fără acces la date, modelul ghicește prețul (aici 30 de lei, în realitate 45). De asta un agent primește tool-uri pentru orice informație care se schimbă: stoc, prețuri, comenzi, programări.
Memoria: lista pe care o trimiți de fiecare dată
API-ul Claude (ca și cel OpenAI) este fără stare: fiecare cerere este judecată doar după ce conține. Modelul nu își amintește conversația de acum un minut; își „amintește” doar pentru că i-o trimiți din nou. Memoria scurtă a agentului este, deci, lista mesaje din codul tău.
Funcția agent de mai jos este bucla din lecția 1, cu o singură diferență importantă: adaugă în listă și răspunsul final al modelului. Fără el, la întrebarea următoare modelul nu ar ști ce a răspuns deja.
import anthropic
MODEL = "claude-haiku-5-5"
client = anthropic.Anthropic()
SYSTEM = "Ești asistentul librăriei Cărturia. Răspunzi scurt și verifici stocul și prețul doar cu tool-urile tale."
CARTI = {
"Enigma Otiliei": {"autor": "G. Călinescu", "stoc": 3, "pret": 45},
"Ion": {"autor": "L. Rebreanu", "stoc": 0, "pret": 39},
}
def cauta_carte(titlu):
c = CARTI.get(titlu)
if not c:
return f"Nu avem cartea {titlu}."
return f"{titlu} de {c['autor']}, {c['stoc']} exemplare în stoc"
def pret_carte(titlu):
c = CARTI.get(titlu)
return f"{c['pret']} lei" if c else f"Nu avem cartea {titlu}."
FUNCTII = {"cauta_carte": cauta_carte, "pret_carte": pret_carte}
TOOLS = [
{"name": "cauta_carte", "description": "Caută o carte după titlu și spune dacă e în stoc.",
"input_schema": {"type": "object", "properties": {"titlu": {"type": "string"}}, "required": ["titlu"]}},
{"name": "pret_carte", "description": "Prețul unei cărți, după titlu.",
"input_schema": {"type": "object", "properties": {"titlu": {"type": "string"}}, "required": ["titlu"]}},
]
def text_din(raspuns):
return " ".join(b.text for b in raspuns.content if b.type == "text")
def agent(mesaje):
"""Bucla agentului: lucrează pe lista primită și adaugă în ea tot ce se întâmplă."""
while True:
raspuns = client.messages.create(model=MODEL, max_tokens=500, system=SYSTEM, tools=TOOLS, messages=mesaje)
mesaje.append({"role": "assistant", "content": raspuns.content}) # și răspunsul final intră în memorie
if raspuns.stop_reason != "tool_use":
return text_din(raspuns)
rezultate = []
for bloc in raspuns.content:
if bloc.type == "tool_use":
rezultate.append({"type": "tool_result", "tool_use_id": bloc.id,
"content": FUNCTII[bloc.name](**bloc.input)})
mesaje.append({"role": "user", "content": rezultate})
istoric = [{"role": "user", "content": "Aveți romanul Enigma Otiliei?"}]
print("Răspuns:", agent(istoric))
print("Mesaje în memorie:", len(istoric))
for m in istoric:
print(" ", m["role"])
Răspuns: Da, avem Enigma Otiliei de G. Călinescu, 3 exemplare în stoc. Mesaje în memorie: 4 user assistant user assistant
| Piesa | Rolul ei | Ce se întâmplă fără ea |
|---|---|---|
| Modelul | decide pasul următor și scrie răspunsul | nu ai agent, ai un script cu pași ficși |
| Tool-urile | aduc date reale și fac acțiuni | modelul inventează prețuri și stocuri |
| Bucla | execută cererile și continuă până la final | programul se oprește la primul tool_use |
| Memoria | lista mesaje, trimisă întreagă la fiecare apel | agentul uită ce a spus clientul |
Greșeli frecvente
- Creezi lista de mesaje din nou la fiecare întrebare. Pare mai „curat”, dar agentul pierde tot contextul: la „și cât costă?” nu mai știe despre ce carte e vorba.
- Nu adaugi răspunsul final al modelului în istoric. Următoarea cerere va avea două mesaje user la rând și modelul nu va ști ce a promis deja clientului.
- Păstrezi memoria într-o variabilă globală comună tuturor clienților. Pe un site cu mai mulți utilizatori, fiecare conversație are lista ei (de exemplu, un dicționar sesiune → mesaje).
- Crezi că modelul „învață” din conversație. Nu se schimbă nimic în model; dacă ștergi lista, totul dispare. Memoria pe termen lung (preferințe, fapte) o construiești separat, în modulul 3.
Memoria scurtă costă: fiecare apel retrimite tot istoricul, deci tokenii de intrare cresc cu fiecare pas. În modulul 3 înveți cum o ții mică (ștergerea rezultatelor vechi, compactarea).
Unde contează fiecare piesă
„Aveți Ion?”, „și în ediție cartonată?”, „cât costă?”: fără memorie, fiecare întrebare pare prima.
Soldul și cursul valutar vin mereu dintr-un tool; un model fără tool-uri ar da cifre plauzibile, dar greșite.
Caută mașina după număr, verifică istoricul reviziilor, propune o programare: bucla face posibile toți cei trei pași.
Clientul librăriei întreabă întâi „Aveți romanul Enigma Otiliei?”, apoi „Și cât costă?”. A doua întrebare are sens doar dacă agentul își amintește titlul. Pune aceeași întrebare de două ori: o dată fără memorie, o dată cu tot istoricul, și compară răspunsurile.
- Prima întrebare este deja în starter: agent(istoric) umple lista istoric cu toți pașii.
- A. Fără memorie: apelează agent cu o listă nouă care conține doar {"role": "user", "content": "Și cât costă?"} și afișează Fără memorie (1 mesaj): <răspuns>.
- B. Cu memorie: adaugă același mesaj în istoric, reține len(istoric) înainte de apel, apelează agent(istoric) și afișează Cu memorie (N mesaje): <răspuns>.
- C. Afișează Mesaje în istoric la final: N (starea reală a memoriei după a doua întrebare).
Soluția exercițiului
import anthropic
MODEL = "claude-haiku-5-5"
client = anthropic.Anthropic()
SYSTEM = "Ești asistentul librăriei Cărturia. Răspunzi scurt și verifici stocul și prețul doar cu tool-urile tale."
CARTI = {
"Enigma Otiliei": {"autor": "G. Călinescu", "stoc": 3, "pret": 45},
"Ion": {"autor": "L. Rebreanu", "stoc": 0, "pret": 39},
}
def cauta_carte(titlu):
c = CARTI.get(titlu)
if not c:
return f"Nu avem cartea {titlu}."
return f"{titlu} de {c['autor']}, {c['stoc']} exemplare în stoc"
def pret_carte(titlu):
c = CARTI.get(titlu)
return f"{c['pret']} lei" if c else f"Nu avem cartea {titlu}."
FUNCTII = {"cauta_carte": cauta_carte, "pret_carte": pret_carte}
TOOLS = [
{"name": "cauta_carte", "description": "Caută o carte după titlu și spune dacă e în stoc.",
"input_schema": {"type": "object", "properties": {"titlu": {"type": "string"}}, "required": ["titlu"]}},
{"name": "pret_carte", "description": "Prețul unei cărți, după titlu.",
"input_schema": {"type": "object", "properties": {"titlu": {"type": "string"}}, "required": ["titlu"]}},
]
def text_din(raspuns):
return " ".join(b.text for b in raspuns.content if b.type == "text")
def agent(mesaje):
"""Bucla agentului: lucrează pe lista primită și adaugă în ea tot ce se întâmplă."""
while True:
raspuns = client.messages.create(model=MODEL, max_tokens=500, system=SYSTEM, tools=TOOLS, messages=mesaje)
mesaje.append({"role": "assistant", "content": raspuns.content}) # și răspunsul final intră în memorie
if raspuns.stop_reason != "tool_use":
return text_din(raspuns)
rezultate = []
for bloc in raspuns.content:
if bloc.type == "tool_use":
rezultate.append({"type": "tool_result", "tool_use_id": bloc.id,
"content": FUNCTII[bloc.name](**bloc.input)})
mesaje.append({"role": "user", "content": rezultate})
istoric = [{"role": "user", "content": "Aveți romanul Enigma Otiliei?"}]
print("Întrebarea 1:", agent(istoric))
nou = [{"role": "user", "content": "Și cât costă?"}]
print(f"Fără memorie (1 mesaj): {agent(nou)}")
istoric.append({"role": "user", "content": "Și cât costă?"})
trimise = len(istoric)
print(f"Cu memorie ({trimise} mesaje): {agent(istoric)}")
print(f"Mesaje în istoric la final: {len(istoric)}") 