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

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.

Tool gândit prostsearch(q)descriere: „Caută.”orice text la q, fără categoriiîntoarce tot catalogul ca JSON[{"nume": "Căști Aria One", "cod": "AU-101", "furnizor": ...modelul ghicește când îl folosește,citește sute de câmpuri inutileTool gândit pentru agentcauta_produse(interogare, categorie, limita=3)descriere: CÂND îl folosești, ce întoarcecategorie: enum audio / laptopuri / telefoaneCăști Aria One | 129 lei | în stocCăști Pulse Sport | 179 lei | în stocCăști Pulse 2 | 199 lei | stoc epuizatși încă 2 rezultate (...)puține linii, exact ce trebuie,plus ce poate face mai departe
Același catalog ElectroCasa, două tool-uri: cel vag întoarce tot catalogul ca JSON, cel gândit pentru agent are categorii fixe, o limită și un rezultat scurt, pe linii.

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"]}}
Bine de știut

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

MagazinCatalog cu mii de produse

Fără limită, o căutare „telefon” ar trimite modelului 800 de rânduri la fiecare pas al buclei.

ClinicăOre libere

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.

ProgramareClaude Code

Tool-urile lui au descrieri lungi, cu exemple și reguli de folosire: echipa le tratează ca pe un prompt.

Exercițiul tău

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.
gasite.sort(key=lambda p: p["pret"]), apoi gasite[:limita] și rest = len(gasite) - limita.

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))
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 7 · Tool-uri gândite pentru agenți
Progres 0% 0 din 10
Lecția curentă 7 / 8 Ce este un agent ai