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

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}}
Important

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}]}
0 · usertext: „Unde e comanda 1042?...”1 · assistanttext + tool_useid=toolu_…00012 · usertool_resulttool_use_id=toolu_…00013 · assistanttext + tool_useid=toolu_…00044 · usertool_resulttool_use_id=toolu_…00045 · assistanttext (end_turn)același idacelași idla fiecare apeltrimiți toată listade la 0 până la ultimul
Cele 6 mesaje ale rulării: fiecare tool_result are tool_use_id egal cu id-ul unui tool_use din mesajul assistant de imediat dinainte.
1
Mesajul 0 (user) are conținut text simplu (un str): întrebarea clientului.
2
Mesajul 1 (assistant) are două blocuri: textul „Verific întâi...” și cererea stare_comanda.
3
Mesajul 2 (user) conține tool_result. Rezultatele au rolul user pentru că le trimite aplicația ta, nu modelul.
4
Mesajele 3 și 4 repetă tiparul pentru estimare_livrare.
5
Mesajul 5 (assistant) are doar text și stop_reason == "end_turn": răspunsul final.

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).

ApelulMesaje trimiseCe decide modelul
10cere stare_comanda
20, 1, 2cere estimare_livrare
30, 1, 2, 3, 4scrie 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

DepanareEroarea 400 din producție

Salvezi mesaje ca JSON când apare eroarea și vezi imediat care tool_result nu are pereche.

SuportAgentul care repetă un pas

În istoric vezi că rezultatul tool-ului era gol, deci modelul l-a cerut din nou.

AuditCe a făcut agentul

Lista de mesaje e jurnalul complet: ce a cerut modelul, cu ce argumente și ce a primit.

Exercițiul tău

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.
tipuri = [b["type"] for b in blocuri] și print(f"{m['role']}: {', '.join(tipuri)}"); la final all(t in tool_use_uri for t in tool_result_uri).

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)
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 3 · Tool use pas cu pas: ce circulă între aplicație și model
Progres 0% 0 din 10
Lecția curentă 3 / 8 Ce este un agent ai