Tool-uri gândite pentru agenți
Modelul nu vede codul tool-urilor tale, ci doar numele, descrierea, schema și rezultatul. Din atât trebuie să decidă când le folosește și ce să înțeleagă din răspuns. De aceea interfața dintre agent și tool contează la fel de mult ca promptul. În această lecție transformi un tool vag într-unul pe care agentul îl folosește corect.
Tool-ul este interfața agentului
În cursul Aplicații AI ai învățat formatul unui tool: name, description, input_schema. La un agent, aceste câmpuri sunt tot ce știe modelul despre lumea ta. Un nume vag sau o descriere de două cuvinte îl obligă să ghicească, iar un rezultat de 5.000 de caractere îi umple contextul cu zgomot la fiecare pas al buclei.
Reguli pentru definiție
- Puține tool-uri, cu granițe clare. Două tool-uri care fac aproape același lucru („cauta_produs”, „gaseste_articol”) îl încurcă pe model.
- Nume de forma acțiune_obiect: cauta_produse, anuleaza_comanda, trimite_email. Modelul înțelege din nume ce face tool-ul.
- Descrierea spune CÂND se folosește și CE întoarce, nu doar ce face. Scrie-o ca pentru un coleg nou.
- Parametri cu tipuri precise: enum pentru valori fixe (categorii, statusuri), description pentru formatul așteptat, required doar pentru ce e cu adevărat obligatoriu.
- O limită de rezultate, cu valoare implicită, ca modelul să nu primească sute de rânduri.
# PROST: nume vag, descriere fără „când”, parametru fără tip clar, fără limită
{"name": "search", "description": "Caută.",
"input_schema": {"type": "object", "properties": {"q": {"type": "string"}}}}
# BUN: acțiune_obiect, când se folosește, ce întoarce, enum, limită cu valoare implicită
{"name": "cauta_produse",
"description": "Caută produse în catalogul ElectroCasa. Folosește-l când clientul întreabă ce produse avem, "
"la ce preț sau dacă sunt în stoc. Întoarce câte un produs pe linie: nume | preț | stoc.",
"input_schema": {"type": "object", "properties": {
"interogare": {"type": "string", "description": "cuvinte din numele produsului, de exemplu „căști”"},
"categorie": {"type": "string", "enum": ["audio", "laptopuri", "telefoane"]},
"limita": {"type": "integer", "description": "câte rezultate, implicit 3"}},
"required": ["interogare", "categorie"]}}
Cu enum, modelul nu poate trimite o categorie inexistentă („căști” în loc de „audio”). Pentru și mai multă siguranță poți adăuga "strict": True și "additionalProperties": False (din cursul Aplicații AI): API-ul garantează atunci că argumentele respectă schema.
Reguli pentru rezultat
Rezultatul tool-ului intră în istoric și este retrimis la fiecare pas următor. Un dump JSON cu toate câmpurile (cod intern, furnizor) costă tokeni și distrage modelul. Compară dimensiunile:
import json
PRODUSE = [
{"nume": "Căști Aria One", "categorie": "audio", "pret": 129, "stoc": 12, "cod": "AU-101", "furnizor": "Aria Sound SRL"},
{"nume": "Căști Pulse 2", "categorie": "audio", "pret": 199, "stoc": 0, "cod": "AU-102", "furnizor": "Pulse Audio SRL"},
{"nume": "Căști SoundMax Pro", "categorie": "audio", "pret": 349, "stoc": 4, "cod": "AU-103", "furnizor": "SoundMax SA"},
{"nume": "Căști Aria Studio", "categorie": "audio", "pret": 459, "stoc": 2, "cod": "AU-104", "furnizor": "Aria Sound SRL"},
{"nume": "Căști Pulse Sport", "categorie": "audio", "pret": 179, "stoc": 7, "cod": "AU-105", "furnizor": "Pulse Audio SRL"},
{"nume": "Boxă Aria Mini", "categorie": "audio", "pret": 149, "stoc": 9, "cod": "AU-201", "furnizor": "Aria Sound SRL"},
{"nume": "Laptop Nova 14", "categorie": "laptopuri", "pret": 3299, "stoc": 3, "cod": "LP-014", "furnizor": "Nova Tech SA"},
{"nume": "Telefon Zen 5", "categorie": "telefoane", "pret": 1899, "stoc": 6, "cod": "TL-005", "furnizor": "Zen Mobile SRL"},
]
dump = json.dumps(PRODUSE, ensure_ascii=False)
print("Dump JSON:", len(dump), "caractere")
linii = [f"{p['nume']} | {p['pret']} lei" for p in PRODUSE if p["categorie"] == "audio"][:3]
print("Rezultat scurt:", len("\n".join(linii)), "caractere")
print("\n".join(linii))
Dump JSON: 984 caractere Rezultat scurt: 77 caractere Căști Aria One | 129 lei Căști Pulse 2 | 199 lei Căști SoundMax Pro | 349 lei
- Doar câmpurile utile sarcinii: numele, prețul, stocul. Codul furnizorului nu ajută la o recomandare.
- Format lizibil: o linie pe rezultat, cu separatori clari. Modelele citesc bine textul simplu.
- Spune ce mai există: „și încă 2 rezultate (mărește limita...)”. Modelul știe că lista nu e completă și ce poate face.
- Erori care spun cum se repară: „Niciun produs pentru „căști” în categoria telefoane. Încearcă un termen mai general.” e mai util decât [] sau Error 404.
Greșeli frecvente
- Descrierea repetă numele („cauta_produse: caută produse”). Nu îi spune modelului când să-l aleagă în locul altui tool.
- Parametrul obligatoriu pe care modelul nu îl poate ști (de exemplu id_intern_categorie: 17). Primește ce știe clientul (numele categoriei) și traduce tu în cod.
- Rezultatul gol fără explicație. Un "" sau [] îl face pe model să creadă că tool-ul a căzut și să-l apeleze din nou, identic.
- Excepții Python lăsate să urce. Un KeyError oprește tot agentul; prinde-l și întoarce un mesaj de eroare cu is_error (lecția despre erori din modulul 2).
Unde se vede diferența
Fără limită, o căutare „telefon” ar trimite modelului 800 de rânduri la fiecare pas al buclei.
ore_libere(medic, zi) cu zi din enum (luni-vineri) în loc de o dată scrisă liber, pe care modelul o poate formata greșit.
Tool-urile lui au descrieri lungi, cu exemple și reguli de folosire: echipa le tratează ca pe un prompt.
Clientul ElectroCasa întreabă: „Ce căști aveți? Vreau ceva ieftin.” Tool-ul din starter e vag și întoarce tot catalogul. Rescrie definiția lui și funcția, după regulile din lecție. Bucla și afișarea rezultatului sunt deja scrise.
- Definiția: descrierea spune când se folosește („Folosește-l când...”) și ce întoarce.
- Parametri: interogare (string) și categorie (string, enum: audio, laptopuri, telefoane), ambii în required; limita (integer, opțional).
- Funcția cauta_produse(interogare, categorie, limita=3): produsele din categorie care conțin interogarea în nume (litere mici), sortate după preț, câte o linie nume | preț lei | în stoc (sau stoc epuizat).
- Maximum limita linii; dacă mai sunt produse, adaugă și încă N rezultate (mărește limita sau rafinează căutarea). Dacă nu găsești nimic, întoarce mesajul din comentariu.
Soluția exercițiului
import json
import anthropic
MODEL = "claude-haiku-5-5"
client = anthropic.Anthropic()
SYSTEM = "Ești asistentul magazinului online ElectroCasa. Recomanzi produse doar din catalog."
PRODUSE = [
{"nume": "Căști Aria One", "categorie": "audio", "pret": 129, "stoc": 12, "cod": "AU-101", "furnizor": "Aria Sound SRL"},
{"nume": "Căști Pulse 2", "categorie": "audio", "pret": 199, "stoc": 0, "cod": "AU-102", "furnizor": "Pulse Audio SRL"},
{"nume": "Căști SoundMax Pro", "categorie": "audio", "pret": 349, "stoc": 4, "cod": "AU-103", "furnizor": "SoundMax SA"},
{"nume": "Căști Aria Studio", "categorie": "audio", "pret": 459, "stoc": 2, "cod": "AU-104", "furnizor": "Aria Sound SRL"},
{"nume": "Căști Pulse Sport", "categorie": "audio", "pret": 179, "stoc": 7, "cod": "AU-105", "furnizor": "Pulse Audio SRL"},
{"nume": "Boxă Aria Mini", "categorie": "audio", "pret": 149, "stoc": 9, "cod": "AU-201", "furnizor": "Aria Sound SRL"},
{"nume": "Laptop Nova 14", "categorie": "laptopuri", "pret": 3299, "stoc": 3, "cod": "LP-014", "furnizor": "Nova Tech SA"},
{"nume": "Telefon Zen 5", "categorie": "telefoane", "pret": 1899, "stoc": 6, "cod": "TL-005", "furnizor": "Zen Mobile SRL"},
]
TOOLS = [
{"name": "cauta_produse",
"description": "Caută produse în catalogul ElectroCasa. Folosește-l când clientul întreabă ce produse avem, "
"la ce preț sau dacă sunt în stoc. Întoarce câte un produs pe linie: nume | preț | stoc.",
"input_schema": {"type": "object", "properties": {
"interogare": {"type": "string", "description": "cuvinte din numele produsului, de exemplu „căști”"},
"categorie": {"type": "string", "enum": ["audio", "laptopuri", "telefoane"]},
"limita": {"type": "integer", "description": "câte rezultate să întoarcă, implicit 3"}},
"required": ["interogare", "categorie"]}},
]
def cauta_produse(interogare, categorie, limita=3):
gasite = [p for p in PRODUSE if p["categorie"] == categorie and interogare.lower() in p["nume"].lower()]
if not gasite:
return f"Niciun produs pentru „{interogare}” în categoria {categorie}. Încearcă un termen mai general."
gasite.sort(key=lambda p: p["pret"])
linii = [f"{p['nume']} | {p['pret']} lei | {'în stoc' if p['stoc'] > 0 else 'stoc epuizat'}" for p in gasite[:limita]]
rest = len(gasite) - limita
if rest > 0:
linii.append(f"și încă {rest} rezultate (mărește limita sau rafinează căutarea)")
return "\n".join(linii)
def text_din(raspuns):
return " ".join(b.text for b in raspuns.content if b.type == "text")
mesaje = [{"role": "user", "content": "Ce căști aveți? Vreau ceva ieftin."}]
while True:
raspuns = client.messages.create(model=MODEL, max_tokens=500, system=SYSTEM, 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":
rezultat = cauta_produse(**bloc.input)
print("Rezultatul tool-ului:")
print(rezultat)
print(f"Caractere trimise modelului: {len(rezultat)} (dump-ul complet: {len(json.dumps(PRODUSE, ensure_ascii=False))})")
rezultate.append({"type": "tool_result", "tool_use_id": bloc.id, "content": rezultat})
mesaje.append({"role": "user", "content": rezultate})
print("Răspuns:", text_din(raspuns)) 