Tool use pas cu pas: ce circulă între aplicație și model
Când un agent greșește, primul lucru pe care îl faci este să te uiți la mesajele care au circulat. În această lecție faci radiografia unei rulări: ce conține fiecare mesaj, ce tipuri de blocuri are, cum se leagă un tool_use de tool_result-ul lui și de ce trimiți tot istoricul la fiecare pas.
De ce te uiți la mesaje
În cursul Aplicații AI ai văzut tool use într-un singur pas: modelul cere, tu execuți, el răspunde. Un agent face asta de mai multe ori la rând, iar lista mesaje crește cu fiecare pas. Dacă înțelegi exact ce e în listă, poți depana orice eroare 400 și orice comportament ciudat al agentului.
Aici folosești un magazin online: clientul întreabă unde e comanda 1042 și când ajunge în Brașov. Agentul are două tool-uri, stare_comanda și estimare_livrare, și le folosește pe rând.
Răspunsul modelului este o listă de blocuri
raspuns.content nu este un text, ci o listă de blocuri. Un bloc text are câmpul text; un bloc tool_use are id, name și input. Modelul poate pune în același răspuns și o frază, și o cerere de tool. Cu bloc.to_dict() vezi exact JSON-ul primit de la API:
import json
import anthropic
MODEL = "claude-haiku-5-5"
client = anthropic.Anthropic()
COMENZI = {1042: "a plecat azi din depozitul din București"}
LIVRARE = {"Brașov": "livrarea în Brașov durează 1-2 zile lucrătoare"}
def stare_comanda(id):
return COMENZI.get(id, f"Comanda {id} nu există.")
def estimare_livrare(oras):
return LIVRARE.get(oras, f"Nu livrăm în {oras}.")
FUNCTII = {"stare_comanda": stare_comanda, "estimare_livrare": estimare_livrare}
TOOLS = [
{"name": "stare_comanda", "description": "Starea unei comenzi după număr.",
"input_schema": {"type": "object", "properties": {"id": {"type": "integer"}}, "required": ["id"]}},
{"name": "estimare_livrare", "description": "Cât durează livrarea într-un oraș.",
"input_schema": {"type": "object", "properties": {"oras": {"type": "string"}}, "required": ["oras"]}},
]
def ca_dict(bloc):
"""Blocurile din răspuns sunt obiecte; cele scrise de tine sunt dicționare. Le aducem la aceeași formă."""
return bloc if isinstance(bloc, dict) else bloc.to_dict()
mesaje = [{"role": "user", "content": "Unde e comanda 1042? Locuiesc în Brașov, când ajunge?"}]
raspuns = client.messages.create(model=MODEL, max_tokens=500, tools=TOOLS, messages=mesaje)
print("stop_reason:", raspuns.stop_reason)
for bloc in raspuns.content:
print(json.dumps(bloc.to_dict(), ensure_ascii=False))
stop_reason: tool_use
{"type": "text", "text": "Verific întâi starea comenzii 1042.", "citations": null}
{"type": "tool_use", "id": "toolu_sim_0001", "name": "stare_comanda", "input": {"id": 1042}}id-ul blocului tool_use (aici toolu_sim_0001) este generat de API. În rularea ta reală va arăta altfel (de exemplu toolu_01A9...), dar regula e aceeași: rezultatul tool-ului trebuie trimis înapoi cu exact acest id, în câmpul tool_use_id.
Istoricul complet al unei rulări
După bucla agentului, lista mesaje conține toată povestea. Exemplul afișează fiecare mesaj ca JSON, pe câte o linie:
import json
import anthropic
MODEL = "claude-haiku-5-5"
client = anthropic.Anthropic()
COMENZI = {1042: "a plecat azi din depozitul din București"}
LIVRARE = {"Brașov": "livrarea în Brașov durează 1-2 zile lucrătoare"}
def stare_comanda(id):
return COMENZI.get(id, f"Comanda {id} nu există.")
def estimare_livrare(oras):
return LIVRARE.get(oras, f"Nu livrăm în {oras}.")
FUNCTII = {"stare_comanda": stare_comanda, "estimare_livrare": estimare_livrare}
TOOLS = [
{"name": "stare_comanda", "description": "Starea unei comenzi după număr.",
"input_schema": {"type": "object", "properties": {"id": {"type": "integer"}}, "required": ["id"]}},
{"name": "estimare_livrare", "description": "Cât durează livrarea într-un oraș.",
"input_schema": {"type": "object", "properties": {"oras": {"type": "string"}}, "required": ["oras"]}},
]
def ca_dict(bloc):
"""Blocurile din răspuns sunt obiecte; cele scrise de tine sunt dicționare. Le aducem la aceeași formă."""
return bloc if isinstance(bloc, dict) else bloc.to_dict()
mesaje = [{"role": "user", "content": "Unde e comanda 1042? Locuiesc în Brașov, când ajunge?"}]
while True:
raspuns = client.messages.create(model=MODEL, max_tokens=500, tools=TOOLS, messages=mesaje)
mesaje.append({"role": "assistant", "content": raspuns.content})
if raspuns.stop_reason != "tool_use":
break
rezultate = []
for bloc in raspuns.content:
if bloc.type == "tool_use":
rezultate.append({"type": "tool_result", "tool_use_id": bloc.id, "content": FUNCTII[bloc.name](**bloc.input)})
mesaje.append({"role": "user", "content": rezultate})
for i, m in enumerate(mesaje):
continut = m["content"] if isinstance(m["content"], str) else [ca_dict(b) for b in m["content"]]
print(i, json.dumps({"role": m["role"], "content": continut}, ensure_ascii=False))
0 {"role": "user", "content": "Unde e comanda 1042? Locuiesc în Brașov, când ajunge?"}
1 {"role": "assistant", "content": [{"type": "text", "text": "Verific întâi starea comenzii 1042.", "citations": null}, {"type": "tool_use", "id": "toolu_sim_0001", "name": "stare_comanda", "input": {"id": 1042}}]}
2 {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "toolu_sim_0001", "content": "a plecat azi din depozitul din București"}]}
3 {"role": "assistant", "content": [{"type": "text", "text": "Comanda a plecat. Verific cât durează livrarea în Brașov.", "citations": null}, {"type": "tool_use", "id": "toolu_sim_0004", "name": "estimare_livrare", "input": {"oras": "Brașov"}}]}
4 {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "toolu_sim_0004", "content": "livrarea în Brașov durează 1-2 zile lucrătoare"}]}
5 {"role": "assistant", "content": [{"type": "text", "text": "Comanda 1042 a plecat azi din depozitul din București, iar livrarea în Brașov durează 1-2 zile lucrătoare, deci o primești cel târziu poimâine.", "citations": null}]}De ce trimiți tot istoricul la fiecare pas
API-ul nu ține minte nimic între cereri. Ca să decidă pasul 3, modelul trebuie să vadă întrebarea, ce a cerut la pasul 1 și ce rezultat a primit. De aceea fiecare apel conține lista întreagă, de la mesajul 0. Rezultatul: cererile devin tot mai mari pe măsură ce agentul lucrează (în modulul 7 calculezi ce înseamnă asta la cost).
| Apelul | Mesaje trimise | Ce decide modelul |
|---|---|---|
| 1 | 0 | cere stare_comanda |
| 2 | 0, 1, 2 | cere estimare_livrare |
| 3 | 0, 1, 2, 3, 4 | scrie răspunsul final |
Greșeli frecvente (și eroarea pe care o primești)
Codul de mai jos trimite un tool_result cu un id inventat. API-ul îl respinge cu eroarea 400:
import json
import anthropic
MODEL = "claude-haiku-5-5"
client = anthropic.Anthropic()
COMENZI = {1042: "a plecat azi din depozitul din București"}
LIVRARE = {"Brașov": "livrarea în Brașov durează 1-2 zile lucrătoare"}
def stare_comanda(id):
return COMENZI.get(id, f"Comanda {id} nu există.")
def estimare_livrare(oras):
return LIVRARE.get(oras, f"Nu livrăm în {oras}.")
FUNCTII = {"stare_comanda": stare_comanda, "estimare_livrare": estimare_livrare}
TOOLS = [
{"name": "stare_comanda", "description": "Starea unei comenzi după număr.",
"input_schema": {"type": "object", "properties": {"id": {"type": "integer"}}, "required": ["id"]}},
{"name": "estimare_livrare", "description": "Cât durează livrarea într-un oraș.",
"input_schema": {"type": "object", "properties": {"oras": {"type": "string"}}, "required": ["oras"]}},
]
def ca_dict(bloc):
"""Blocurile din răspuns sunt obiecte; cele scrise de tine sunt dicționare. Le aducem la aceeași formă."""
return bloc if isinstance(bloc, dict) else bloc.to_dict()
mesaje = [{"role": "user", "content": "Unde e comanda 1042?"}]
raspuns = client.messages.create(model=MODEL, max_tokens=500, tools=TOOLS, messages=mesaje)
mesaje.append({"role": "assistant", "content": raspuns.content})
# GREȘIT: id-ul inventat nu corespunde niciunui tool_use din mesajul anterior
mesaje.append({"role": "user", "content": [{"type": "tool_result", "tool_use_id": "toolu_123", "content": "a plecat"}]})
raspuns = client.messages.create(model=MODEL, max_tokens=500, tools=TOOLS, messages=mesaje)
Mesajul de eroare este unexpected tool_use_id found in tool_result blocks: toolu_123. Each tool_result block must have a corresponding tool_use block in the previous message. Pe românește: fiecare rezultat trebuie să răspundă unei cereri din mesajul assistant de imediat dinainte.
- Rezultatul fără cererea lui: ai uitat mesaje.append({"role": "assistant", "content": raspuns.content}) înainte de rezultate. Eroarea e aceeași: tool_use_id necunoscut.
- Cererea fără rezultat: modelul a cerut două tool-uri și tu ai trimis un singur rezultat. Eroarea: tool_use ids were found without tool_result blocks immediately after.
- Tratezi blocurile ca dicționare: blocurile din raspuns.content sunt obiecte (bloc.type), cele scrise de tine sunt dicționare (bloc["type"]). Funcția ca_dict le aduce la aceeași formă.
- Pui ceva între cerere și rezultat: un mesaj user cu text între tool_use și tool_result rupe legătura. Dacă vrei să adaugi text, pune-l în același mesaj, după blocurile tool_result.
Unde îți folosește radiografia
Salvezi mesaje ca JSON când apare eroarea și vezi imediat care tool_result nu are pereche.
În istoric vezi că rezultatul tool-ului era gol, deci modelul l-a cerut din nou.
Lista de mesaje e jurnalul complet: ce a cerut modelul, cu ce argumente și ce a primit.
Bucla agentului magazinului a rulat deja (e în starter). Fă radiografia istoricului: afișează rolul și tipurile blocurilor fiecărui mesaj, numără cererile de tool și rezultatele și verifică în cod că fiecare tool_result are perechea lui tool_use.
- Parcurge mesaje. Pentru conținut str tipurile sunt ["text"]; altfel transformă blocurile cu ca_dict și ia b["type"].
- Afișează pentru fiecare mesaj rol: tipuri (tipurile separate prin , ), de exemplu assistant: text, tool_use.
- Pune în tool_use_uri id-urile blocurilor tool_use și în tool_result_uri valorile tool_use_id ale blocurilor tool_result, apoi afișează tool_use: N | tool_result: M.
- Calculează legaturi = all(...) (fiecare tool_use_id se găsește printre id-urile tool_use) și afișează Legături corecte: True.
- Ultima linie (Răspuns: ...) e deja în starter.
Soluția exercițiului
import json
import anthropic
MODEL = "claude-haiku-5-5"
client = anthropic.Anthropic()
COMENZI = {1042: "a plecat azi din depozitul din București"}
LIVRARE = {"Brașov": "livrarea în Brașov durează 1-2 zile lucrătoare"}
def stare_comanda(id):
return COMENZI.get(id, f"Comanda {id} nu există.")
def estimare_livrare(oras):
return LIVRARE.get(oras, f"Nu livrăm în {oras}.")
FUNCTII = {"stare_comanda": stare_comanda, "estimare_livrare": estimare_livrare}
TOOLS = [
{"name": "stare_comanda", "description": "Starea unei comenzi după număr.",
"input_schema": {"type": "object", "properties": {"id": {"type": "integer"}}, "required": ["id"]}},
{"name": "estimare_livrare", "description": "Cât durează livrarea într-un oraș.",
"input_schema": {"type": "object", "properties": {"oras": {"type": "string"}}, "required": ["oras"]}},
]
def ca_dict(bloc):
"""Blocurile din răspuns sunt obiecte; cele scrise de tine sunt dicționare. Le aducem la aceeași formă."""
return bloc if isinstance(bloc, dict) else bloc.to_dict()
mesaje = [{"role": "user", "content": "Unde e comanda 1042? Locuiesc în Brașov, când ajunge?"}]
while True:
raspuns = client.messages.create(model=MODEL, max_tokens=500, tools=TOOLS, messages=mesaje)
mesaje.append({"role": "assistant", "content": raspuns.content})
if raspuns.stop_reason != "tool_use":
break
rezultate = []
for bloc in raspuns.content:
if bloc.type == "tool_use":
rezultate.append({"type": "tool_result", "tool_use_id": bloc.id, "content": FUNCTII[bloc.name](**bloc.input)})
mesaje.append({"role": "user", "content": rezultate})
tool_use_uri = []
tool_result_uri = []
for m in mesaje:
if isinstance(m["content"], str):
tipuri = ["text"]
else:
blocuri = [ca_dict(b) for b in m["content"]]
tipuri = [b["type"] for b in blocuri]
for b in blocuri:
if b["type"] == "tool_use":
tool_use_uri.append(b["id"])
if b["type"] == "tool_result":
tool_result_uri.append(b["tool_use_id"])
print(f"{m['role']}: {', '.join(tipuri)}")
print(f"tool_use: {len(tool_use_uri)} | tool_result: {len(tool_result_uri)}")
legaturi = all(t in tool_use_uri for t in tool_result_uri)
print(f"Legături corecte: {legaturi}")
print("Răspuns:", raspuns.content[-1].text) 