Gândește, acționează, observă: tiparul ReAct
Un agent care doar cere tool-uri e greu de înțeles: vezi ce a făcut, dar nu și de ce. Tiparul ReAct (Reason + Act) îi cere modelului să scrie un gând scurt înainte de fiecare acțiune. Pașii devin explicabili, iar tu poți depana agentul citind gândurile lui.
Ce este ReAct
ReAct vine de la „Reasoning and Acting”, o idee publicată în 2022: modelul alternează gândul (ce știu, ce îmi lipsește, ce fac acum), acțiunea (un tool) și observația (rezultatul tool-ului). Ciclul se repetă până când modelul are destule informații pentru răspuns.
Cu API-ul Claude, ReAct e simplu: răspunsul modelului poate conține un bloc text înaintea blocului tool_use. Acel text este gândul. Tu doar îi ceri modelului, în system prompt, să-l scrie de fiecare dată.
Cum îl ceri: o frază în system prompt
Agenția de turism Voiaj are două tool-uri, cauta_zboruri și vremea. System promptul de mai jos cere un gând înainte de fiecare tool. Uită-te la primul răspuns al modelului:
import anthropic
MODEL = "claude-haiku-5-5"
client = anthropic.Anthropic()
ZBORURI = {("Barcelona", "vineri"): "RO-412, București 07:40 → Barcelona 10:15, 489 lei"}
VREMEA = {("Barcelona", "vineri"): "însorit, 24°C ziua și 16°C seara"}
def cauta_zboruri(destinatie, zi):
return ZBORURI.get((destinatie, zi), f"Niciun zbor spre {destinatie} {zi}.")
def vremea(oras, zi):
return VREMEA.get((oras, zi), f"Nu am prognoza pentru {oras}.")
FUNCTII = {"cauta_zboruri": cauta_zboruri, "vremea": vremea}
TOOLS = [
{"name": "cauta_zboruri", "description": "Zborurile din București spre o destinație, într-o zi a săptămânii.",
"input_schema": {"type": "object", "properties": {"destinatie": {"type": "string"}, "zi": {"type": "string"}},
"required": ["destinatie", "zi"]}},
{"name": "vremea", "description": "Prognoza meteo pentru un oraș, într-o zi a săptămânii.",
"input_schema": {"type": "object", "properties": {"oras": {"type": "string"}, "zi": {"type": "string"}},
"required": ["oras", "zi"]}},
]
CERERE = "Vreau să zbor vineri la Barcelona. Ce iau în bagaj?"
SYSTEM = ("Ești agentul de călătorii al Agenției Voiaj. Înainte de fiecare tool, explică într-o frază "
"de ce îl folosești și ce speri să afli.")
raspuns = client.messages.create(model=MODEL, max_tokens=500, system=SYSTEM, tools=TOOLS,
messages=[{"role": "user", "content": CERERE}])
for bloc in raspuns.content:
if bloc.type == "text":
print("text:", bloc.text)
elif bloc.type == "tool_use":
print("tool_use:", bloc.name, bloc.input)
text: Clientul vrea să ajungă vineri la Barcelona, deci caut întâi zborurile din București pentru ziua aceea.
tool_use: cauta_zboruri {'destinatie': 'Barcelona', 'zi': 'vineri'}Fără instrucțiunea despre explicații, același model cere de obicei direct tool-ul, fără text. Programul de mai jos ar afișa doar ['tool_use']: știi ce a ales modelul, dar nu și de ce.
import anthropic
MODEL = "claude-haiku-5-5"
client = anthropic.Anthropic()
ZBORURI = {("Barcelona", "vineri"): "RO-412, București 07:40 → Barcelona 10:15, 489 lei"}
VREMEA = {("Barcelona", "vineri"): "însorit, 24°C ziua și 16°C seara"}
def cauta_zboruri(destinatie, zi):
return ZBORURI.get((destinatie, zi), f"Niciun zbor spre {destinatie} {zi}.")
def vremea(oras, zi):
return VREMEA.get((oras, zi), f"Nu am prognoza pentru {oras}.")
FUNCTII = {"cauta_zboruri": cauta_zboruri, "vremea": vremea}
TOOLS = [
{"name": "cauta_zboruri", "description": "Zborurile din București spre o destinație, într-o zi a săptămânii.",
"input_schema": {"type": "object", "properties": {"destinatie": {"type": "string"}, "zi": {"type": "string"}},
"required": ["destinatie", "zi"]}},
{"name": "vremea", "description": "Prognoza meteo pentru un oraș, într-o zi a săptămânii.",
"input_schema": {"type": "object", "properties": {"oras": {"type": "string"}, "zi": {"type": "string"}},
"required": ["oras", "zi"]}},
]
CERERE = "Vreau să zbor vineri la Barcelona. Ce iau în bagaj?"
SYSTEM = "Ești agentul de călătorii al Agenției Voiaj." # fără cererea de a explica pașii
raspuns = client.messages.create(model=MODEL, max_tokens=500, system=SYSTEM, tools=TOOLS,
messages=[{"role": "user", "content": CERERE}])
print([b.type for b in raspuns.content]) # de obicei doar ['tool_use']: nu știi DE CE a ales pasul
Modelele Claude au și un raționament intern (extended / adaptive thinking), cu blocuri separate de tip thinking, controlat de API. Gândul ReAct e altceva: un text obișnuit, scurt, scris pentru tine și pentru jurnal, cerut prin prompt. Îl poți afișa utilizatorului sau salva în loguri.
O rulare completă, pas cu pas
Animația arată exact rularea din exercițiu. Primul gând explică de ce caută zborul; al doilea, de ce cere vremea după ce a găsit zborul. Când citești jurnalul unei rulări greșite, gândurile îți spun unde a raționat greșit modelul: a înțeles cererea altfel? a ignorat o observație?
De ce merită
| Avantaj | Ce câștigi concret |
|---|---|
| Depanare | vezi de ce a ales un tool greșit (a înțeles greșit cererea, a citit greșit un rezultat) |
| Interfață | afișezi utilizatorului „Caut zborurile...”, ca să nu aștepte în tăcere |
| Audit | jurnalul spune ce a făcut agentul și cu ce motiv |
| Calitate | modelul care își scrie planul pas cu pas alege de obicei mai bine pasul următor |
Costul: fiecare gând înseamnă câțiva tokeni de ieșire în plus pe pas. Pentru agenți interni, cu volum mare, poți renunța la gânduri; pentru suport și depanare, merită aproape mereu.
Greșeli frecvente
- **Citești doar raspuns.content[0] ca tool.** Cu ReAct, primul bloc e textul, iar tool_use vine după el. Parcurge toate blocurile și verifică bloc.type.
- Ceri gânduri lungi. „Explică pe larg” umple contextul și costul. Cere o singură frază.
- Tratezi gândul ca pe un adevăr. Gândul e explicația modelului, nu o dovadă. Deciziile importante le verifici în cod (lecțiile despre siguranță din modulul 6).
- Arăți gândurile oricui, oricum. Un gând poate menționa date interne („clientul are restanțe”). Decide ce afișezi utilizatorului și ce rămâne doar în jurnal.
ReAct în produse reale
„Caut întâi zborul, apoi hotelul aproape de aeroport”: utilizatorul vede progresul.
Agentul scrie scurt ce urmează să facă („rulez testele ca să văd ce pică”) înainte de fiecare comandă.
Fiecare pas al agentului ajunge în tichet cu motivul lui, iar colegul care preia cazul înțelege ce s-a încercat.
Transformă agentul Agenției Voiaj într-un agent ReAct: cere în system prompt un gând înainte de fiecare tool, apoi afișează pentru fiecare pas gândul, acțiunea și observația. La final, numără câți pași nu au avut gând (starea reală a rulării).
- Completează SYSTEM cu instrucțiunea: înainte de fiecare tool, modelul explică într-o frază de ce îl folosește.
- În buclă, după ce adaugi răspunsul în mesaje, afișează Gând: <text> (textul blocurilor text din răspuns; dacă e gol, afișează Gând: (niciunul) și crește fara_gand).
- Pentru fiecare tool_use, afișează Acțiune: nume(input) (de exemplu Acțiune: vremea({'oras': 'Barcelona', 'zi': 'vineri'})) și Observație: <rezultat>.
- Ultimele două linii (Răspuns: și Pași fără gând:) sunt deja în starter.
Soluția exercițiului
import anthropic
MODEL = "claude-haiku-5-5"
client = anthropic.Anthropic()
ZBORURI = {("Barcelona", "vineri"): "RO-412, București 07:40 → Barcelona 10:15, 489 lei"}
VREMEA = {("Barcelona", "vineri"): "însorit, 24°C ziua și 16°C seara"}
def cauta_zboruri(destinatie, zi):
return ZBORURI.get((destinatie, zi), f"Niciun zbor spre {destinatie} {zi}.")
def vremea(oras, zi):
return VREMEA.get((oras, zi), f"Nu am prognoza pentru {oras}.")
FUNCTII = {"cauta_zboruri": cauta_zboruri, "vremea": vremea}
TOOLS = [
{"name": "cauta_zboruri", "description": "Zborurile din București spre o destinație, într-o zi a săptămânii.",
"input_schema": {"type": "object", "properties": {"destinatie": {"type": "string"}, "zi": {"type": "string"}},
"required": ["destinatie", "zi"]}},
{"name": "vremea", "description": "Prognoza meteo pentru un oraș, într-o zi a săptămânii.",
"input_schema": {"type": "object", "properties": {"oras": {"type": "string"}, "zi": {"type": "string"}},
"required": ["oras", "zi"]}},
]
CERERE = "Vreau să zbor vineri la Barcelona. Ce iau în bagaj?"
SYSTEM = ("Ești agentul de călătorii al Agenției Voiaj. Înainte de fiecare tool, explică într-o frază "
"de ce îl folosești și ce speri să afli.")
def text_din(raspuns):
return " ".join(b.text for b in raspuns.content if b.type == "text")
mesaje = [{"role": "user", "content": CERERE}]
fara_gand = 0
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})
gand = text_din(raspuns)
if not gand:
fara_gand += 1
gand = "(niciunul)"
print(f"Gând: {gand}")
rezultate = []
for bloc in raspuns.content:
if bloc.type == "tool_use":
rezultat = FUNCTII[bloc.name](**bloc.input)
print(f"Acțiune: {bloc.name}({bloc.input})")
print(f"Observație: {rezultat}")
rezultate.append({"type": "tool_result", "tool_use_id": bloc.id, "content": rezultat})
mesaje.append({"role": "user", "content": rezultate})
print("Răspuns:", text_din(raspuns))
print("Pași fără gând:", fara_gand) 