Construiți un agent AI care funcționează: Un glosar practic

Un agent AI este un program care ia un obiectiv, decide o secvență de acțiuni și execută acele acțiuni folosind instrumente până când obiectivul este atins sau renunță. Asta diferă de un chatbot, care doar răspunde la mesaje. Un agent planifică, apelează funcții, verifică rezultatele și se ajustează. Dacă ați folosit ChatGPT doar prin browser, construirea primului agent este punctul în care modelul încetează să fie un generator de text și devine o componentă într-un sistem mai mare.

Bucla de bază

Fiecare agent, indiferent cum este promovat, rulează o versiune a aceleiași bucle: observă, gândește, acționează, repetă. Concret:

1. Agentul primește o sarcină ("găsește cel mai ieftin zbor către Lisabona luna viitoare și redactează un rezumat prin email").
2. Apelează LLM-ul cu sarcina plus o descriere a instrumentelor disponibile.
3. Modelul întoarce fie un răspuns final, fie un apel la instrument, cum ar fi search_flights(destination="Lisbon", month="2025-06").
4. Codul dumneavoastră execută acea funcție, obține un rezultat real și o alimentează înapoi în contextul modelului.
5. Modelul decide ce să facă mai departe: apelează alt instrument, cere clarificări sau termină.

Acest pattern se numește adesea bucla ReAct (reason plus act), și este coloana vertebrală a unor framework-uri cum ar fi agentul executor din LangChain, agenți LlamaIndex și function-calling API din OpenAI. Puteți implementa totul singuri în sub 100 linii de Python cu doar o API LLM și o buclă while — framework-urile adaugă comoditate, nu magie.

Instrumentele sunt ce fac din asta un agent

Un model fără instrumente poate doar să vorbească. Dați-i funcții și poate acționa. Instrumentele sunt de obicei funcții Python simple înfășurate cu o schemă care descrie numele, parametrii și scopul lor, pentru ca modelul să știe când și cum să le apeleze. Exemplu:

def get_weather(city: str) -> str:
    """Return current weather for a given city."""
    resp = requests.get(f"https://api.weather.example/v1/{city}")
    return resp.json()["summary"]

Cu function-calling din OpenAI, treceți o schemă JSON alături de această funcție, și modelul produce un apel structurat cum ar fi {"name": "get_weather", "arguments": {"city": "Lisbon"}} în loc de text liber. Codul dumneavoastră parsează asta, rulează funcția reală și întoarce rezultatul ca un nou mesaj în conversație. Repetați până când modelul are suficiente informații pentru a răspunde.

Memorie și stare

Un singur apel API nu are memorie dincolo de fereastra lui de context. Agenții au nevoie de stare explicită: o listă în curs de mesaje (istoricul conversației) și adesea un depozit separat pentru fapte pe termen mai lung. Pentru sarcini scurte, o listă Python de dicționare reprezentând conversația este suficientă. Pentru agenți care trebuie să rețină lucruri pe sesiuni, veți apela la o bază de date vectorială (Chroma, Pinecone, Qdrant) pentru a stoca și recupera informații relevante din trecut prin embedding-uri.

Nu supraînginizați asta devreme. Un număr surprinzător de proiecte de "agent" eșuează nu pentru că LLM-ul este slab, ci pentru că gestionarea stării este neglijentă: mesaje duplicate, creștere nelimitată a contextului, sau pierderea urmăririi ce apel de instrument corespunde ce rezultat.

Un exemplu minim care funcționează

Iată structura unui agent minimal folosind API-ul OpenAI, fără framework:

messages = [{"role": "user", "content": "What's the weather in Lisbon?"}]

while True:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
        tools=[weather_tool_schema],
    )
    msg = response.choices[0].message
    if msg.tool_calls:
        for call in msg.tool_calls:
            result = get_weather(**json.loads(call.function.arguments))
            messages.append(msg)
            messages.append({
                "role": "tool",
                "tool_call_id": call.id,
                "content": result,
            })
    else:
        print(msg.content)
        break

Acesta este un agent real și funcțional. Totul altceva — strategii de planificare, coordonare multi-agent, pipeline-uri de recuperare — se construiește pe această buclă.

Unde se defectează

Agenții eșuează în moduri previzibile: bucle infinite de apeluri la instrumente când modelul nu poate spune că a reușit, argumente de funcție halucinante și costuri în scop din apelarea repetată de instrumente scumpe. Protejați-vă împotriva buclelor cu o limită de iterații strictă (să zicem, 10 pași) și înregistrați fiecare apel la instrument în timpul dezvoltării. Validați argumentele înainte de a executa orice care atinge un sistem real — un agent care poate trimite email-uri sau rula comenzi shell are nevoie de aceeași igienă a intrării pe care o aplicați codului orientat spre utilizator, pentru că LLM-ul este, în esență, un utilizator neîncrezător care generează acea intrare.

Unde mergeți mai departe

Odată ce bucla funcționează, problemele interesante încep: alegerea între design-uri single-agent și multi-agent, deciderea cât de mult autonomie să acordați și testarea agenților într-un mod fiabil când ieșirea lor nu este deterministă. Pistele de AI și Python din Korra Studio acoperă generarea augmentată de recuperare, design-ul promptului și pattern-uri de apel la instrumente în mai multă profunzime dacă doriți să continuați construirea de aici.