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

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.

1. Modeluldecide ce urmează2. Tool-urilecauta_carte, pret_carte3. Buclawhile ... tool_use4. Memoriaistoric = [ ... ]cere toolrezultattot istoricultrimite din noulipsește o piesă?agentul se strică
Cele patru piese ale agentului de librărie: modelul cere un tool, rezultatul intră în memorie, bucla trimite tot istoricul înapoi la model.

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
Atenție

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
1
user: întrebarea clientului.
2
assistant: modelul cere cauta_carte (bloc tool_use).
3
user: rezultatul tool-ului (bloc tool_result; rezultatele au rolul user, pentru că vin din aplicația ta).
4
assistant: răspunsul final, pentru client.
PiesaRolul eiCe se întâmplă fără ea
Modeluldecide pasul următor și scrie răspunsulnu ai agent, ai un script cu pași ficși
Tool-urileaduc date reale și fac acțiunimodelul inventează prețuri și stocuri
Buclaexecută cererile și continuă până la finalprogramul se oprește la primul tool_use
Memorialista mesaje, trimisă întreagă la fiecare apelagentul 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.
Bine de știut

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ă

LibrărieÎntrebări în lanț

„Aveți Ion?”, „și în ediție cartonată?”, „cât costă?”: fără memorie, fiecare întrebare pare prima.

BancăDate care se schimbă

Soldul și cursul valutar vin mereu dintr-un tool; un model fără tool-uri ar da cifre plauzibile, dar greșite.

Service autoMai mulți pași

Caută mașina după număr, verifică istoricul reviziilor, propune o programare: bucla face posibile toți cei trei pași.

Exercițiul tău

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).
La B nu creezi o listă nouă: istoric.append({"role": "user", "content": "Și cât costă?"}), apoi agent(istoric). Ar trebui să trimiți 5 mesaje.

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)}")
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 2 · Cele patru piese: model, tool-uri, buclă, memorie
Progres 0% 0 din 10
Lecția curentă 2 / 8 Ce este un agent ai