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

Primul tău agent: modelul care decide singur pașii

Un chatbot răspunde o dată și gata. Un agent primește un obiectiv, alege singur ce tool-uri să folosească, în ce ordine, și se oprește când a terminat. În această lecție rulezi un agent adevărat de 30 de linii, pentru o firmă de curierat, și vezi exact ce face la fiecare pas.

Ce este un agent AI

În cursul Aplicații AI ai trimis cereri la model, ai definit tool-uri și ai văzut cum modelul cere un tool cu un bloc tool_use. Acum faci pasul următor: lași modelul să conducă. Nu mai scrii tu „întâi caută coletul, apoi verifică programul”; îi dai tool-urile și sarcina, iar el decide pașii.

Un agent are patru piese: modelul (decide), tool-urile (funcțiile tale pe care le poate cere), bucla (codul care execută ce cere modelul și îi trimite rezultatul, din nou și din nou) și memoria (lista de mesaje, unde rămâne tot ce s-a întâmplat). Peste ele stă obiectivul: ce trebuie rezolvat.

Clientul„RO200 ajunge azi?”bucla agentului (codul tău, while)Modelulalege pasul următorTool-uriurmareste_coletprogram_livrareMemoria: lista mesajecererea, pașii modelului, rezultatele tool-urilortool_useresultRăspunsend_turn
Bucla agentului: modelul cere tool-uri, codul tău le execută, totul rămâne în memorie, până când modelul dă răspunsul final (end_turn).

Gândește-te la un dispecer nou într-o firmă de curierat. Nu îi dai un scenariu pentru fiecare întrebare posibilă; îi dai acces la sistemul de urmărire și la programul curierilor și îl lași să afle singur ce îi trebuie ca să-i răspundă clientului. Agentul face același lucru, doar că „accesul” sunt funcțiile tale Python.

Primul agent, de rulat

Codul de mai jos este un agent complet. Datele (coletele, programul) sunt într-un dicționar, ca să poți vedea totul; într-o firmă reală, funcțiile ar citi dintr-o bază de date sau dintr-un API intern. Citește comentariile din buclă: acolo e toată ideea.

import anthropic

MODEL = "claude-haiku-5-5"
client = anthropic.Anthropic()

COLETE = {
    "RO100": "în tranzit spre Iași, livrare estimată mâine",
    "RO200": "în depozitul din Cluj, pleacă azi cu mașina de livrare",
}
PROGRAM = {
    "Cluj": "În Cluj curierii livrează între 9:00 și 18:00",
    "Iași": "În Iași curierii livrează între 10:00 și 19:00",
}


def urmareste_colet(awb):
    return COLETE.get(awb, f"Nu există niciun colet cu AWB-ul {awb}.")


def program_livrare(oras):
    return PROGRAM.get(oras, f"Nu livrăm încă în {oras}.")


FUNCTII = {"urmareste_colet": urmareste_colet, "program_livrare": program_livrare}
TOOLS = [
    {"name": "urmareste_colet", "description": "Starea unui colet după AWB (de exemplu RO100).",
     "input_schema": {"type": "object", "properties": {"awb": {"type": "string"}}, "required": ["awb"]}},
    {"name": "program_livrare", "description": "Intervalul orar în care livrează curierii într-un oraș.",
     "input_schema": {"type": "object", "properties": {"oras": {"type": "string"}}, "required": ["oras"]}},
]


def text_din(raspuns):
    return " ".join(b.text for b in raspuns.content if b.type == "text")


mesaje = [{"role": "user", "content": "Unde este coletul RO100?"}]   # memoria: tot ce s-a spus
while True:                                                           # bucla
    raspuns = client.messages.create(model=MODEL, max_tokens=500, tools=TOOLS, messages=mesaje)
    if raspuns.stop_reason != "tool_use":                             # modelul a terminat
        break
    mesaje.append({"role": "assistant", "content": raspuns.content})
    rezultate = []
    for bloc in raspuns.content:
        if bloc.type == "tool_use":                                   # modelul cere un tool
            print("Modelul cere:", bloc.name, bloc.input)
            rezultat = FUNCTII[bloc.name](**bloc.input)               # codul tău îl execută
            rezultate.append({"type": "tool_result", "tool_use_id": bloc.id, "content": rezultat})
    mesaje.append({"role": "user", "content": rezultate})

print("Răspuns:", text_din(raspuns))
Modelul cere: urmareste_colet {'awb': 'RO100'}
Răspuns: Coletul tău este în tranzit spre Iași, livrare estimată mâine.

Observă că nu ai scris nicăieri „apelează urmareste_colet”. Modelul a citit întrebarea, a văzut descrierile tool-urilor și a ales singur. Codul tău doar execută și raportează.

API-ul este simulat

În lecții, modulul anthropic este un simulator: aceeași interfață ca biblioteca reală, răspunsuri pregătite pentru exercițiul lecției, fără cheie, fără internet și fără cost. Același program rulează neschimbat în proiectul tău după pip install anthropic și o cheie API în ANTHROPIC_API_KEY.

Ce se întâmplă la fiecare pas

1
Trimiți la model întrebarea și lista de tool-uri (tools=TOOLS).
2
Modelul răspunde cu stop_reason == "tool_use" și un bloc tool_use: numele tool-ului și argumentele ({'awb': 'RO100'}).
3
Adaugi răspunsul modelului în mesaje, execuți funcția din FUNCTII și trimiți rezultatul ca tool_result, cu același tool_use_id.
4
Bucla trimite din nou toată conversația. Modelul vede rezultatul și decide: încă un tool sau răspunsul final.
5
Când stop_reason nu mai este tool_use, bucla se oprește și afișezi textul.

Animația arată exact sarcina din exercițiu: două tool-uri, în ordinea aleasă de model. La o altă întrebare („unde e RO100?”) agentul face un singur pas. Același cod, drumuri diferite: asta îl face agent.

Agent, chatbot sau script?

Cine decide pașiiCe poate faceExemplu
Chatbotnimeni: un singur apelrăspunde din ce știerăspunsuri la întrebări generale
Script / workflowtu, în codpași ficși, mereu aceiașirezumă fiecare email și salvează-l
Agentmodelul, la fiecare pasalege tool-uri până terminărezolvă cererea unui client

Un agent nu e mereu răspunsul potrivit: costă mai mult (mai multe apeluri) și e mai greu de prevăzut. În lecția 4 înveți când e mai bine un workflow simplu. Pentru cereri variate, unde nu știi dinainte de ce date e nevoie, agentul câștigă.

Greșeli frecvente

  • **Uiți să adaugi răspunsul modelului în mesaje** înainte de tool_result. API-ul răspunde cu eroarea 400: fiecare tool_result trebuie să aibă un tool_use în mesajul de dinainte.
  • Trimiți rezultatele în mesaje separate. Toate rezultatele unui pas merg într-un singur mesaj user, ca listă.
  • **Citești doar raspuns.content[0].text.** Când modelul scrie și text, și cere un tool, primul bloc poate fi text; parcurge blocurile și verifică bloc.type.
  • Bucla fără ieșire. Aici ieșirea e break când stop_reason != "tool_use". În lecțiile următoare adaugi și o limită de pași, obligatorie în producție.

Agenți în aplicații reale

CurieratAsistentul de pe site

Află starea coletului, programul din oraș și, dacă e nevoie, reprogramează livrarea.

SuportHelpdesk IT

Caută în tichete, citește ghidul VPN și deschide un tichet nou doar dacă problema nu e cunoscută.

ProgramareClaude Code

Un agent care citește fișiere, rulează teste și editează cod, pas cu pas, până trec testele.

Exercițiul tău

Clientul întreabă: „Coletul RO200 ajunge azi? Sunt în Cluj.” Scrie bucla agentului, ca agentul să afle singur starea coletului și programul de livrare din Cluj. Ai în starter datele, tool-urile și dicționarul FUNCTII.

  • Scrie bucla while True: care trimite client.messages.create(model=MODEL, max_tokens=500, tools=TOOLS, messages=mesaje).
  • Ieși din buclă cu break când raspuns.stop_reason nu este "tool_use".
  • Altfel, adaugă răspunsul în mesaje cu rolul assistant.
  • Pentru fiecare bloc tool_use: crește pas, afișează Pas N: nume input (de exemplu Pas 1: urmareste_colet {'awb': 'RO200'}), execută funcția din FUNCTII și pregătește un tool_result.
  • Trimite toate rezultatele într-un singur mesaj user. Ultima linie (Răspuns: ...) e deja în starter.
Ai bucla completă în exemplul din lecție; aici adaugi doar contorul pas și afișarea print(f"Pas {pas}: {bloc.name} {bloc.input}").

Soluția exercițiului

import anthropic

MODEL = "claude-haiku-5-5"
client = anthropic.Anthropic()

COLETE = {
    "RO100": "în tranzit spre Iași, livrare estimată mâine",
    "RO200": "în depozitul din Cluj, pleacă azi cu mașina de livrare",
}
PROGRAM = {
    "Cluj": "În Cluj curierii livrează între 9:00 și 18:00",
    "Iași": "În Iași curierii livrează între 10:00 și 19:00",
}


def urmareste_colet(awb):
    return COLETE.get(awb, f"Nu există niciun colet cu AWB-ul {awb}.")


def program_livrare(oras):
    return PROGRAM.get(oras, f"Nu livrăm încă în {oras}.")


FUNCTII = {"urmareste_colet": urmareste_colet, "program_livrare": program_livrare}
TOOLS = [
    {"name": "urmareste_colet", "description": "Starea unui colet după AWB (de exemplu RO100).",
     "input_schema": {"type": "object", "properties": {"awb": {"type": "string"}}, "required": ["awb"]}},
    {"name": "program_livrare", "description": "Intervalul orar în care livrează curierii într-un oraș.",
     "input_schema": {"type": "object", "properties": {"oras": {"type": "string"}}, "required": ["oras"]}},
]


def text_din(raspuns):
    return " ".join(b.text for b in raspuns.content if b.type == "text")


mesaje = [{"role": "user", "content": "Coletul RO200 ajunge azi? Sunt în Cluj."}]
pas = 0
while True:
    raspuns = client.messages.create(model=MODEL, max_tokens=500, tools=TOOLS, messages=mesaje)
    if raspuns.stop_reason != "tool_use":
        break
    mesaje.append({"role": "assistant", "content": raspuns.content})
    rezultate = []
    for bloc in raspuns.content:
        if bloc.type == "tool_use":
            pas += 1
            print(f"Pas {pas}: {bloc.name} {bloc.input}")
            rezultat = FUNCTII[bloc.name](**bloc.input)
            rezultate.append({"type": "tool_result", "tool_use_id": bloc.id, "content": rezultat})
    mesaje.append({"role": "user", "content": rezultate})

print("Răspuns:", text_din(raspuns))
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 1 · Primul tău agent: modelul care decide singur pașii
Progres 0% 0 din 10
Lecția curentă 1 / 8 Ce este un agent ai