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.
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ă.
Î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
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șii | Ce poate face | Exemplu | |
|---|---|---|---|
| Chatbot | nimeni: un singur apel | răspunde din ce știe | răspunsuri la întrebări generale |
| Script / workflow | tu, în cod | pași ficși, mereu aceiași | rezumă fiecare email și salvează-l |
| Agent | modelul, la fiecare pas | alege 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
Află starea coletului, programul din oraș și, dacă e nevoie, reprogramează livrarea.
Caută în tichete, citește ghidul VPN și deschide un tichet nou doar dacă problema nu e cunoscută.
Un agent care citește fișiere, rulează teste și editează cod, pas cu pas, până trec testele.
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.
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)) 