Cele mai bune practici de tool calling pentru agenți: de ce alege agentul tău instrumentul greșit

Cele mai bune practici de tool calling pentru agenți: de ce alege agentul tău instrumentul greșit

Practicile de tool calling pentru agenți sunt ceea ce stă între un demo funcțional și un agent care, în liniște, cheamă instrumentul greșit în producție. Echipa de inginerie de la Anthropic a măsurat cum o singură descriere rescrisă a redus un rezultat de instrument de la 206 tokenuri la 72, iar Claude Code limitează acum fiecare răspuns de instrument la maximum 25.000 de tokenuri, pentru că scurgerea este reală. Agentul tău eșuează în patru feluri: instrument greșit, argumente greșite, bucle necontrolate și pierdere de tokenuri, iar fiecare are o corecție pe care o poți livra săptămâna aceasta.

Idei principale:

• Tool calling-ul pentru agenți eșuează în exact patru feluri: instrument greșit, argumente greșite, bucle necontrolate și pierdere de tokenuri.
• Descrierile instrumentelor sunt singura instrucțiune pe care modelul o vede la momentul selecției, deci ele rezolvă majoritatea apelurilor de instrument greșit.
• Schemele plate, croite pe sarcină, cu inputuri validate, elimină majoritatea eșecurilor de argumente greșite.
• Răspunsurile concise ale instrumentelor și o buclă de evaluare la fiecare schimbare țin costul tokenurilor și regresiile măsurabile.

De ce eșuează tool calling-ul pentru agenți în producție?

Tool calling-ul pentru agenți eșuează în patru feluri: modelul alege instrumentul greșit, scrie argumente greșite, se învârte într-o buclă necontrolată sau pierde tokenuri prin răspunsuri supraîncărcate. Fiecare eșec lovește un pas diferit al buclei de apel, deci ordinea corecțiilor contează. Începe cu selecția, pentru că o alegere greșită a instrumentului otrăvește fiecare pas care urmează.

Rețeta completă, dintr-o privire:

Parcurge-le în această ordine. Practicile 1 și 2 durează o după-amiază și elimină majoritatea eșecurilor de instrument greșit și de argumente greșite pe care le vezi azi. O descriere de instrument nu este documentație. Este singura instrucțiune pe care modelul o primește la momentul selecției.

Faza 1: Proiectează instrumente pe care modelul le poate folosi cu adevărat

Cele mai ieftine câștiguri de fiabilitate în tool calling-ul pentru agenți se află în definițiile instrumentelor tale, nu în prompturi sau în alegerea modelului. Modelul nu îți citește niciodată documentația API sau README-ul. Vede un nume, un șir de descriere și o schemă JSON și decide doar pe baza lor. Nimerește aceste trei elemente și acuratețea selecției se îmbunătățește înainte să atingi orice altceva.

Practica 1: Scrie descrieri pe care modelul se poate baza

Scrie descrierile instrumentelor ca instrucțiuni pentru model, nu ca documentație API. O descriere care mulțumește un dezvoltator uman („wrapper REST pentru endpoint-ul de users") nu oferă modelului nimic pe care să decidă. Ghidul de inginerie Anthropic despre scrierea instrumentelor și bunele practici de definire a instrumentelor promovează ambele același tipar: spune când să folosești instrumentul, ce returnează și când să NU îl folosești.

{
  "name": "get_user",
  "description": "Fetches a user profile. Use ONLY when you already have a user_id. Do NOT use to search or list users; call search_users instead. Returns name, email, plan. Errors if user_id is not a valid UUID."
}

față de versiunea pe care o livrează majoritatea echipelor:

{
  "name": "get_user",
  "description": "Gets a user."
}

Două reguli fac cea mai mare parte din treabă aici. Prima: numește parametrii astfel încât sensul lor să fie lipsit de ambiguitate: user_id, niciodată user sau id, pentru că user invită modelul să paseze un nume sau un email acolo unde ar trebui un UUID. A doua: formulează excluderile explicit. „A NU se folosi pentru a căuta utilizatori" previne mai multe apeluri de instrument greșit decât orice cantitate de descriere pozitivă, deoarece modelele încurcă instrumentele care se suprapun mult mai des decât înțeleg greșit instrumentele unice, clar delimitate. Pentru mecanica la nivel de provider, cum ajung aceste definiții la API-urile OpenAI, Anthropic și Google, vezi ghidul nostru de function calling multi-provider.

Practica 2: Păstrează schemele plate și croite pe sarcină

Păstrează schemele de input plate, cu fiecare câmp de care sarcina are cu adevărat nevoie și fără cele de care nu are nevoie. Obiectele imbricate cu ramuri opționale sunt locul unde se înmulțesc eșecurile de argumente greșite: modelul trebuie să infer o structură pentru care nu vede niciodată exemple. Ghidul OpenAI de function calling acceptă JSON Schema arbitrar, dar permisiv nu înseamnă același lucru cu fiabil.

{
  "name": "create_ticket",
  "parameters": {
    "type": "object",
    "properties": {
      "ticket": {
        "type": "object",
        "properties": {
          "details": {
            "type": "object",
            "properties": {
              "title": { "type": "string" },
              "meta": { "type": "object" }
            }
          }
        }
      }
    }
  }
}

Aplatizeaz-o pe sarcină:

{
  "name": "create_ticket",
  "parameters": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "priority": { "type": "string", "enum": ["low", "medium", "high"] },
      "assignee_id": { "type": "string" }
    },
    "required": ["title", "priority"]
  }
}

Enum-urile înving textul liber pentru orice câmp cu un set mărginit de valori. Câmpurile obligatorii înving tot ce este opțional. Dacă modelul are aproape mereu nevoie de un câmp, fă-l obligatoriu în schema instrumentului chiar și atunci când API-ul tău îl numește opțional. Nu oglindești API-ul tău. Proiectezi o suprafață pe care un anumit model o poate completa corect.

Faza 2: Gestionează setul de instrumente, nu doar instrumentele

Calitatea individuală a instrumentelor nu mai este suficientă din momentul în care un agent poartă mai mult de câteva instrumente, pentru că erorile de selecție cresc odată cu dimensiunea listei pe care modelul o citește.

Practica 3: Împachetează secvențele API multi-pas în instrumente atomice

Comprimă orice secvență fixă de apeluri API într-un singur instrument atomic. Articolul de inginerie Anthropic folosește schedule_event și get_customer_context ca model: un singur apel care face toată treaba învinge trei apeluri pe care agentul trebuie să le înlănțuie corect de fiecare dată. Fiecare verigă dintr-un lanț este o nouă tură în care modelul poate bloca, poate reîncerca greșit sau poate intra în buclă.

# What the agent does WITHOUT an atomic tool: 3 calls, 3 chances to fail
calendar = call_tool("list_calendars", {})
free = call_tool("find_free_slot", {"calendar_id": calendar["items"][0]["id"], "duration": 30})
call_tool("create_event", {"calendar_id": calendar["items"][0]["id"], "start": free["start"]})

# One atomic tool: the sequence lives in your code, not the model's head
call_tool("schedule_event", {"duration": 30, "attendees": ["[email protected]"]})

Regula practică: dacă modelul trebuie mereu să cheme B după A, atunci A și B sunt un singur instrument care poartă două costume.

Practica 4: Namespace, curățare și filtrare dinamică a instrumentelor

Pune un namespace pe fiecare nume de instrument și arată fiecărui agent doar submulțimea de care sarcina lui curentă are nevoie. Numele generice intră în coliziune în momentul în care conectezi două integrări. Imaginează-ți un agent legat la două servere MCP care expun ambele un instrument numit search: două verbe identice, fără nicio cale de a le deosebi. Anthropic documentează câștiguri măsurabile de evaluare din namespacing-ul cu prefix:

Curățarea contează la fel de mult ca numirea. Un agent de suport nu are nevoie de instrumentele de facturare încărcate în timp ce răspunde la o întrebare despre parolă. Tiparul planner-worker, în care un planner direcționează o sarcină către un worker care încarcă doar instrumentele relevante, este corecția standard; ghidul LangGraph de încărcare dinamică a instrumentelor parcurge implementarea. Câte instrumente înseamnă prea multe? Tratează 5-10 per agent ca interval de lucru, nu ca lege: acuratețea se degradează pe măsură ce lista crește, iar leacul este filtrarea, nu un model mai mare. Dacă alegi chiar stratul de rutare și filtrare, compară-ți opțiunile în selecția noastră cu cele mai bune biblioteci de function calling.

Faza 3: Controlează ce se întoarce și ce iese

Bucla rulează în ambele direcții, iar majoritatea echipelor proiectează doar jumătatea de ieșire. Ceea ce returnează instrumentele tale determină cât din fereastra de context supraviețuiește până la tura următoare, iar ceea ce respinge validarea ta determină dacă modelul învață din greșelile lui sau le repetă.

Practica 5: Returnează rezultate concise, cu semnal puternic

Returnează cel mai mic rezultat pe care modelul poate acționa, cu identificatori lizibili pentru oameni în loc de ID-uri brute. Articolul de inginerie Anthropic documentează un instrument al cărui rezultat implicit ajungea la 206 de tokenuri; o setare concisă response_format a redus același rezultat la 72 de tokenuri, aproximativ o treime din dimensiune. Înmulțește asta cu zeci de apeluri per sarcină și devine factorul care decide dacă agentul tău mai termină vreodată.

// Before: 206 tokens (shape per Anthropic's documented example)
{
  "status": "success",
  "data": {
    "id": "8f14e45f-ceea-3f9c-a2f3-90c1b5e0a7d2",
    "object": "task", "created_at": "2026-07-02T09:14:00Z",
    "updated_at": "2026-07-11T16:40:12Z", "completed_at": null,
    "assignee": {"id": "c9a1...f2", "object": "user"},
    "projects": [{"id": "b7d3...91", "object": "project"}],
    "permalink": "https://app.asana.com/0/.../f"
  }
}

// After: 72 tokens
{ "task": "Fix login redirect", "assignee": "Dana Kim", "project": "Web App", "due": "2026-07-20" }

Încă două detalii din aceeași sursă: Anthropic suportă un enum response_format (detaliat versus concis) pe definițiile instrumentelor, astfel încât poți declara forma pe care o vrei în loc să parsezi un flux uriaș. Iar Claude Code limitează răspunsurile instrumentelor la 25.000 de tokenuri, un plafon fix care trunchiază oricum rezultatele umflate. Anthropic raportează de asemenea, ca constatare proprie, că rezolvarea UUID-urilor în nume semantice a redus măsurabil halucinațiile de recuperare, motiv pentru care payload-ul „după" de mai sus spune „Dana Kim" și nu c9a1...f2. Răspunsurile supraîncărcate sunt și o problemă de cost; vezi ghidul nostru despre reducerea costurilor API LLM pentru imaginea completă.

Practica 6: Validează fiecare apel și fă erorile să instruiască modelul

Validează fiecare apel de instrument pe server și returnează erori care conțin corecția. Articolul lui Martin Fowler despre function calling o spune fără ocolișuri: nu avea niciodată încredere în output-ul modelului. Va pasa șiruri de text acolo unde ar trebui enum-uri și va inventa ID-uri care nu există.

def create_ticket(args):
    if args.get("priority") not in {"low", "medium", "high"}:
        return {"error": f"priority must be one of: low, medium, high. Got '{args.get('priority')}'. Pass priority='medium' for normal issues."}
    if not is_valid_uuid(args.get("assignee_id")):
        return {"error": "assignee_id must be a UUID. Call list_team_members to get valid IDs, then retry."}
    return db.create_ticket(**args)

Șirul de eroare este toată miza. Compară:

# Unhelpful: the model retries the same bad call
{"error": "invalid input"}

# Helpful: the model knows exactly what to change
{"error": "priority must be one of: low, medium, high. Got 'urgent'. Use 'high'."}

Fiecare eroare de validare pe care instrumentul tău o returnează este un prompt pe care îl scrii pentru următoarea încercare a modelului. Erorile care numesc constrângerea și indică instrumentul de corecție transformă o buclă de reîncercări într-o recuperare dintr-o singură mișcare. Aceasta este și prima ta linie de apărare de securitate; ghidul nostru de guardrails LLM o acoperă în detaliu.

Faza 4: Cum o faci sigură, apoi cum o faci măsurabilă?

Siguranța și măsurarea sunt aceeași fază, deoarece o acțiune distructivă fără poartă și o regresie nemăsurată apar ambele ca incidente pe care nu le-ai putut prevedea. Pune porți pe acțiunile care nu pot fi anulate, apoi instrumentează totul, astfel încât următoarea schimbare de instrument să fie o decizie cu dovezi în spate, nu o speranță.

Practica 7: Pune acțiunile distructive în spatele unui om

Separă instrumentele de citire de cele de scriere și pune o poartă de confirmare umană pe orice este distructiv. Adnotările de instrument din specificația MCP există exact pentru asta: destructiveHint marchează instrumentele care efectuează actualizări distructive, iar openWorldHint semnalează instrumentele care ating sisteme externe, astfel încât clienții pot cere confirmare înainte de executare. Folosește-le.

Modul de eșec nu este ipotetic. Laurent Kubaski a documentat un caz, în articolul său din iulie 2025 despre tool calling, cu raportul original atașat, în care un utilizator a cerut Copilot în Excel să acționeze pe rândul 4, iar agentul a acționat în schimb pe rândul 8. Nicio poartă de confirmare nu stătea între rândul greșit și scriere. Corecția este tiparul pe care AWS îl documentează pentru Bedrock Agents: agentul pregătește acțiunea, o returnează pentru aprobare și o execută doar după ce un om confirmă. Cursor face la fel pentru editările de fișiere. Limitează credențialele la doar citire acolo unde citirea este tot ce are nevoie sarcina și tratează porțile de confirmare ca parte a suprafeței tale de injecție, subiectul ghidului nostru de prevenire a prompt injection.

Practica 8: Rulează o buclă de evaluare la fiecare schimbare de instrument

Rulează o suită mică de evaluare înainte și după fiecare schimbare de instrument și citește metricile într-o ordine fixă. Ghidul de optimizare Paragon propune un cadru de patru metrici care merită adoptat:

Cookbook-ul Anthropic de evaluare a instrumentelor, construit pe evaluări MCP reale de Slack și Asana, arată cum arată sarcinile de evaluare bune și rele:

# Weak: vague, many valid paths, impossible to score
"Use the Asana tools to organize some work."

# Strong: one correct tool, checkable arguments, binary outcome
"Create a task titled 'Renew TLS cert' in project 'Infra' assigned to [email protected], due 2026-08-15. Expect exactly one create_task call with those four fields."

Interpretarea noastră, etichetată ca atare: cifrele publicate îți dau ordinea de lucru. Verifică mai întâi corectitudinea instrumentului, deoarece propriile măsurători Anthropic arată că schimbările de descriere și de numire o influențează direct (rescrierea de la 206 la 72 de tokenuri, constatarea despre halucinația UUID-la-nume) și lasă eficiența sarcinii la final, deoarece ea reflectă mai ales eșecuri pe care primele trei metrici le-au detectat deja. Pentru suita de început, proiectează 15-30 de sarcini, două sau trei per instrument, fiecare cu un singur apel așteptat și o condiție binară de reușită. Acea dimensiune este suficientă pentru a prinde o regresie dintr-o rescriere de descriere fără o săptămână de etichetare, iar noi citim configurarea Slack și Asana din cookbook ca dovadă că o suită atât de mică este punctul de plecare intenționat, nu o scurtătură. Mecanica mai profundă se află în ghidul nostru de evaluare a agenților AI în producție, iar dacă rezultatele evaluării spun că instrumentele în sine sunt bune, dar orchestrarea nu, atunci este momentul să îți revizuiești alegerea de framework în raport cu cele mai bune framework-uri de agenți AI.

Tool calling pentru agenți vs MCP: care este diferența?

MCP este un standard de transport și registru, nu un strat de fiabilitate, deci aceleași opt practici se aplică indiferent dacă instrumentele tale sosesc prin MCP sau sunt definite inline. Tool calling-ul nativ este contractul dintre model și provider: cum emite modelul un tool_call și citește un tool_result. MCP standardizează modul în care instrumentele ajung la model; nu face nimic în privința dacă modelul îl alege pe cel potrivit.

Un server MCP care expune un instrument numit search cu descrierea „caută lucruri" eșuează identic cu o funcție inline definită în același fel. Repară definiția, apoi fă-ți griji despre transport. Ghidul nostru Model Context Protocol acoperă partea de protocol de la un capăt la altul.

Cum aplică Techsy aceste opt practici

La fiecare construcție de agent pentru un client, impunem trei dintre acestea înainte ca orice altceva să fie livrat: descrieri scrise ca instrucțiuni (Practica 1), porți de validare pe fiecare instrument de scriere (Practica 6) și o suită de evaluare care rulează înainte de deploy, nu după un incident (Practica 8). Aceste trei acoperă apelurile de instrument greșit, apelurile cu argumente greșite și regresiunile care le reintroduc pe ambele, adică exact locul de unde a început fiecare incident de agent în producție pe care l-am depanat. Celelalte cinci practici urmează pe măsură ce agentul crește. Dacă agentul tău a trecut de faza de demo și alege instrumentele greșite, solicită o consultație gratuită și îți vom spune pe care dintre cele opt să o repari prima.

Despre autor

Mert Batur este co-fondator al Techsy.io, unde echipa livrează agenți AI, sisteme de automatizare și pipeline-uri de voce/SDR pentru clienți B2B. El scrie despre stack-ul de instrumente LLM pe care echipa Techsy îl folosește efectiv în producție. Conectează-te pe LinkedIn.

Întrebări frecvente

Ce este tool calling-ul pentru agenți?

Tool calling-ul pentru agenți este mecanismul prin care un LLM decide să invoce o funcție externă, emite un tool_call structurat și așteaptă ca codul tău să returneze un tool_result peste care poate raționa. Este ceea ce transformă un model de chat într-un agent care poate interoga baze de date, poate apela API-uri și poate întreprinde acțiuni: modelul alege instrumentul și argumentele, executorul tău le rulează.

Cum funcționează bucla de tool calling pentru agenți?

Bucla are cinci pași: cererea utilizatorului ajunge la model, modelul selectează un instrument și scrie un tool_call, executorul tău îl rulează, un tool_result se întoarce la model, iar modelul fie răspunde, fie emite un alt apel. Acel ciclu se repetă până când sarcina este gata. Cele patru moduri de eșec din acest ghid se află fiecare la un pas specific al acestei bucle.

De ce alege agentul meu instrumentul greșit?

De obicei pentru că două instrumente se suprapun, iar descrierile lor nu spun care este care. Modelul selectează doar pe baza numelor și descrierilor, deci „ia un utilizator" versus „găsește utilizatori" pare interschimbabil. Repară asta cu linii de excludere („a NU se folosi pentru a căuta"), nume cu namespace și mai puține instrumente în context. Testul lui Kubaski pe patru modele a arătat că până și modelele puternice se direcționează greșit pe liste ambigue.

Cum forțez un agent de tool calling să își structureze output-ul?

Constrânge schema, nu promptul. Folosește enum-uri pentru câmpuri mărginite, câmpuri obligatorii pentru orice are nevoie sarcina și obiecte plate în locul celor imbricate. Pentru răspunsul final, nu pentru apelul de instrument, funcții ale providerului precum output-ul structurat OpenAI și modurile tool-choice ale Anthropic forțează o formă specifică. Ghidul nostru de output structurat acoperă ambele căi, cu cod.

Tool calling pentru agenți vs MCP: care este diferența?

Tool calling-ul nativ este contractul dintre codul tău și un provider de model: formatul mesajelor tool_call și tool_result. MCP este un strat de protocol care standardizează modul în care instrumentele sunt descoperite și livrate oricărui client compatibil. MCP schimbă conductele, nu fiabilitatea. Un instrument descris prost eșuează în același fel pe oricare cale, după cum explică ghidul nostru Model Context Protocol.

Câte instrumente înseamnă prea multe pentru un agent LLM?

Tratează 5-10 instrumente per agent ca interval de lucru, nu ca lege. Acuratețea selecției se degradează pe măsură ce lista vizibilă crește, mai ales când numele sau descrierile se suprapun. Soluția nu este un model mai mare, ci filtrarea: încarcă doar submulțimea de care sarcina curentă are nevoie, folosind o împărțire planner-worker. Pune namespace pe tot, astfel încât două integrări să nu expună niciodată ambele un search simplu.

Care este cel mai bun model pentru tool calling?

Nu există un răspuns unic, iar benchmark-urile publicate îmbătrânesc prost în acest domeniu. Modelele de frontieră de la OpenAI, Anthropic și Google rezolvă toate sarcinile de bază de utilizare a instrumentelor, în timp ce modele mai mici, combinate cu instrumente bine proiectate, finalizează adesea sarcinile aproape la fel de des, la o fracțiune din costul tokenurilor. Construiește suita de evaluare de 15-30 de sarcini din Practica 8 și testează candidații pe propriile tău instrumente.

Cum reduc costul tokenurilor din tool calling?

Taie din ce se întoarce. Returnează rezultate concise, cu semnal puternic, în loc de payload-uri API brute: Anthropic a documentat o reducere de la 206 la 72 de tokenuri dintr-o singură schimbare de response_format. Rezolvă UUID-urile în nume, elimină câmpurile pe care modelul nu le folosește niciodată și amintește-ți că fiecare rezultat de instrument reintră în fereastra de context la fiecare tură următoare. Mai puține apeluri, prin instrumente atomice, elimină rezultate întregi din factură.

Cum evaluez calitatea tool calling-ului?

Scorizează patru metrici, în ordine: corectitudinea instrumentului (instrumentul potrivit?), acuratețea inputului (argumente valide?), finalizarea sarcinii (obiectiv atins?) și eficiența sarcinii (număr de tokenuri și de apeluri?). Scrie 15-30 de sarcini, fiecare așteptând un singur apel specific, cu argumente verificabile și o condiție binară de reușită. Rulează suita înainte și după fiecare schimbare de instrument, astfel încât o rescriere de descriere să nu fie niciodată livrată nemăsurată.

Concluzie

Diagnostichează înainte să optimizezi. Agentul tău alege instrumentul greșit din unul dintre patru motive, iar trei dintre cele opt practici de mai sus, descrierile, schemele plate și filtrarea, repară eșecurile de selecție care provoacă majoritatea incidentelor din producție. Începe de acolo, pentru că ele costă o după-amiază și sunt motivul pentru care această problemă poate fi rezolvată. Păstrează erorile de validare informative, pune orice acțiune distructivă în spatele unui om și rulează bucla de evaluare la fiecare schimbare, astfel încât să măsori înainte să schimbi modele. Problema instrumentului greșit nu este o problemă de model. Este o problemă de proiectare a instrumentelor, iar proiectarea îți aparține.