Ghid pentru înțelegerea, crearea și optimizarea agenților API

Rolul Inteligenței Artificiale în companiile tehnologice evoluează rapid; cazurile de utilizare a IA au evoluat de la prelucrarea pasivă a informațiilor la agenți proactivi capabili să execute sarcini. Conform unui sondaj din martie 2025 privind adoptarea globală a IA, realizat de Georgian și NewtonX, 91% dintre directorii tehnici din companiile aflate în faza de creștere și din întreprinderi utilizează sau intenționează să utilizeze IA agențială.

Agenții care apelează API sunt un exemplu primar al acestei schimbări către agenți. Agenții care apelează API utilizează Modele de Limbaj Mare (LLM) pentru a interacționa cu sisteme software prin Interfețele lor de Programare a Aplicațiilor (API).

De exemplu, prin traducerea comenzilor în limbaj natural în apeluri API precise, agenții pot recupera date în timp real, automatiza sarcini repetitive sau chiar controla alte sisteme software. Această capacitate transformă agenții IA în intermediari utili între intenția umană și funcționalitatea software.

Companiile utilizează în prezent agenți care apelează API în diverse domenii, inclusiv:

• Aplicații pentru consumatori: Asistenți precum Siri de la Apple sau Alexa de la Amazon au fost proiectați pentru a simplifica sarcinile zilnice, cum ar fi controlul dispozitivelor inteligente pentru casă și efectuarea de rezervări.
• Fluxuri de lucru enterprise: Întreprinderile au implementat agenți API pentru a automatiza sarcini repetitive, cum ar fi recuperarea de date din CRM, generarea de rapoarte sau consolidarea informațiilor din sisteme interne.
• Recuperare și analiză de date: Întreprinderile utilizează agenți API pentru a simplifica accesul la seturi de date proprietare, resurse bazate pe abonament și API publice, pentru a genera insight-uri.

În acest articol, voi utiliza o abordare centrată pe inginerie pentru a înțelege, crea și optimiza agenții care apelează API. Materialul din acest articol se bazează parțial pe cercetarea și dezvoltarea practică efectuate de Laboratorul de IA al companiei Georgian. Întrebarea motivatoare pentru o mare parte a cercetării Laboratorului de IA în domeniul agenților care apelează API a fost: “Dacă o organizație are un API, care este cel mai eficient mod de a crea un agent care să poată interacționa cu acel API utilizând limbaj natural?”

Voi explica cum funcționează agenții care apelează API și cum să proiectați și să inginerizați cu succes acești agenți pentru performanță. În cele din urmă, voi oferi un flux de lucru sistematic pe care echipele de ingineri îl pot utiliza pentru a implementa agenții care apelează API.

I. Definiții cheie:

• API sau Interfață de Programare a Aplicațiilor: Un set de reguli și protocoale care permit diferitelor aplicații software să comunice și să schimbe informații.
• Agenț: Un sistem de inteligență artificială proiectat pentru a percepe mediul, a lua decizii și a efectua acțiuni pentru a atinge obiective specifice.
• Agenț care apelează API: Un agent de inteligență artificială specializat care traduce instrucțiuni în limbaj natural în apeluri API precise.
• Agenț generativ de cod: Un sistem de inteligență artificială care asistă în dezvoltarea software prin scrierea, modificarea și depanarea codului. Deși este legat, accentul meu aici se pune în principal pe agenții care apelează API, deși IA poate ajuta și la construirea acestor agenți.
• Protocolul de Context al Modelului (MCP): Un protocol, în special dezvoltat de Anthropic, care definește modul în care LLM pot conecta și utiliza surse de date și instrumente externe.

II. Sarcina de bază: Traducerea limbajului natural în acțiuni API

Funcția fundamentală a unui agent care apelează API este de a interpreta o cerere în limbaj natural a utilizatorului și de a o converti în una sau mai multe apeluri API precise. Acest proces implică de obicei:

1. Recunoașterea intenției: Înțelegerea obiectivului utilizatorului, chiar dacă este exprimat în mod ambiguu.
2. Selecția instrumentului: Identificarea punctului/punctelor de terminare API adecvat(e) – sau “instrumentelor” – dintr-un set de opțiuni disponibile care pot îndeplini intenția.
3. Extracția parametrilor: Identificarea și extragerea parametrilor necesari pentru apelul/apelurile API selectat(e) din interogarea utilizatorului.
4. Execuția și generarea răspunsului: Efectuarea apelului/apelurilor API, primirea răspunsului/răspunsurilor și apoi sintetizarea acestei informații într-un răspuns coerent sau efectuarea unei acțiuni ulterioare.

Luați în considerare o solicitare precum “Hey Siri, ce vreme este astăzi?” Agenția trebuie să identifice nevoia de a apela un API meteo, să determine locația curentă a utilizatorului (sau să permită specificarea unei locații) și apoi să formuleze apelul API pentru a obține informațiile meteo.

Pentru solicitarea “Hey Siri, ce vreme este astăzi?”, un apel API de exemplu ar putea arăta astfel:

GET /v1/weather?location=New%20York&units=metric

Provocările inițiale de nivel înalt sunt inerente în acest proces de traducere, inclusiv ambiguitatea limbajului natural și nevoia agenției de a menține contextul pe parcursul interacțiunilor cu mai multe etape.

De exemplu, agenția trebuie adesea să “memoreze” părți anterioare ale unei conversații sau rezultatele apelurilor API anterioare pentru a informa acțiunile curente. Pierderea contextului este un mod de eșec comun dacă nu este gestionat explicit.

III. Proiectarea soluției: Componente și protocoale cheie

Crearea de agenți care apelează API eficienți necesită o abordare arhitecturală structurată.

1. Definirea “Instrumentelor” pentru Agenție

Pentru ca un LLM să utilizeze un API, capacitățile acelui API trebuie descrise într-un mod pe care îl poate înțelege. Fiecare punct de terminare API sau funcție este adesea reprezentat ca un “instrument”. O definiție robustă a instrumentului include:

• O descriere clară în limbaj natural a scopului și funcționalității instrumentului.
• O specificație precisă a parametrilor de intrare (nume, tip, dacă este necesar sau opțional și o descriere).
• O descriere a ieșirii sau a datelor pe care instrumentul le returnează.

2. Rolul Protocolului de Context al Modelului (MCP)

MCP este un factor cheie pentru o utilizare mai standardizată și mai robustă a instrumentelor de către LLM. Acesta oferă un format structurat pentru definirea modului în care modelele pot conecta și utiliza surse de date și instrumente externe.

Standardizarea MCP este benefică deoarece permite o integrare mai ușoară a unor instrumente diverse, promovează reutilizarea definițiilor instrumentelor în diferiți agenți sau modele. Mai mult, este o practică recomandată pentru echipele de ingineri, începând cu specificații API bine definite, cum ar fi o specificație OpenAPI. Unelte precum Stainless.ai sunt proiectate pentru a ajuta la conversia acestor specificații OpenAPI în configurații MCP, simplificând procesul de a face API “gata pentru agenți”.

3. Cadrul și alegerile de implementare ale Agenției

Mai multe cadruri pot ajuta la construirea agenției în sine. Acestea includ:

• Pydantic: Deși nu este exclusiv un cadru pentru agenții, Pydantic este util pentru definirea structurilor de date și asigurarea siguranței tipurilor pentru intrările și ieșirile instrumentelor, ceea ce este important pentru fiabilitate. Multe implementări personalizate de agenții utilizează Pydantic pentru această integritate structurală.
• Agentul mcp al LastMile: Acest cadru este proiectat special pentru a lucra cu MCP, oferind o structură mai opinioasă care se aliniază cu practicile pentru construirea de agenți eficienți, așa cum sunt descrise în cercetările din locuri precum Anthropic.
• Cadru intern: De asemenea, este din ce în ce mai obișnuit să se utilizeze agenți de cod generativ IA (utilizând unelte precum Cursor sau Cline) pentru a ajuta la scrierea codului de bază pentru agenție, instrumentele sale și logica înconjurătoare. Experiența Laboratorului de IA al companiei Georgian, care lucrează cu companii pe implementări agențiale, arată că acest lucru poate fi excelent pentru crearea unor cadruri personalizate minimale.

IV. Ingineria pentru fiabilitate și performanță

Asigurarea faptului că un agent efectuează apeluri API fiabile și are o performanță bună necesită un efort de inginerie concentrat. Două modalități de a face acest lucru sunt (1) crearea și validarea setului de date și (2) ingineria și optimizarea prompturilor.

1. Crearea și validarea setului de date

Antrenarea (dacă este aplicabilă), testarea și optimizarea unui agent necesită un set de date de înaltă calitate. Acest set de date ar trebui să constea în interogări în limbaj natural reprezentative și secvențele de apeluri API corespunzătoare sau rezultate.

• Creație manuală: Curățarea manuală a unui set de date asigură precizie și relevanță ridicată, dar poate fi laborioasă.
• Generare sintetică: Generarea de date în mod programatic sau utilizând LLM poate scala crearea setului de date, dar această abordare prezintă provocări semnificative. Cercetarea Laboratorului de IA al companiei Georgian a constatat că asigurarea corectitudinii și complexității realiste a apelurilor API și interogărilor generate sintetic este foarte dificilă. Adesea, întrebările generate erau fie prea triviale, fie imposibil de complexe, făcând dificilă măsurarea performanței nuanțate a agentului. Validarea atentă a datelor sintetice este absolut critică.

Pentru evaluarea critică, un set de date mai mic, de înaltă calitate, verificat manual, oferă adesea perspective mai fiabile decât unul mare și zgomotos, generat sintetic.

2. Ingineria și optimizarea prompturilor

Performanța unui agent bazat pe LLM este puternic influențată de prompturile utilizate pentru a ghida raționamentul și selecția instrumentului său.

• Un prompt eficient implică definirea clară a sarcinii agentului, oferirea de descrieri ale instrumentelor disponibile și structurarea promptului pentru a încuraja extragerea precisă a parametrilor.
• Optimizarea sistematică utilizând cadruri precum DSPy poate îmbunătăți semnificativ performanța. DSPy permite definirea componentelor agentului (de exemplu, module pentru generarea de gânduri, selecția instrumentelor, formatarea parametrilor) și apoi utilizează o abordare similară unui compilator, cu exemple de aruncare din setul de date, pentru a găsi prompturi sau configurații optimizate pentru aceste componente.

V. Un drum recomandat către agenți API eficienți

Dezvoltarea de agenți AI robusti care apelează API este o disciplină inginerică iterativă. Pe baza descoperirilor cercetării Laboratorului de IA al companiei Georgian, rezultatele pot fi îmbunătățite semnificativ utilizând un flux de lucru sistematic, cum ar fi următorul:

1. Începeți cu definiții API clare: Începeți cu specificații OpenAPI structurate pentru API-urile cu care va interacționa agentul.
2. Standardizați accesul la instrumente: Convertiți specificațiile OpenAPI în instrumente MCP. Unelte precum Stainless.ai pot facilita acest proces, creând un mod standardizat pentru agentul dvs. să înțeleagă și să utilizeze API-urile.
3. Implementați agentul: Alegeți un cadru sau o abordare adecvată. Acest lucru ar putea implica utilizarea Pydantic pentru modelarea datelor într-o structură de agent personalizată sau utilizarea unui cadru precum agentul mcp al LastMile, care este construit în jurul MCP.
   • Înainte de a face acest lucru, luați în considerare conectarea MCP la un instrument precum Claude Desktop sau Cline și utilizați manual această interfață pentru a obține o senzație de cât de bine un agent generic poate utiliza MCP, câte iterații necesită de obicei pentru a utiliza MCP corect și orice alte detalii care v-ar putea economisi timpul în timpul implementării.
4. Curați un set de date de evaluare de calitate: Creați manual sau validați cu atenție un set de date de interogări și interacțiuni API așteptate. Acest lucru este critic pentru testarea și optimizarea fiabilă.
5. Optimizați prompturile și logica agentului: Utilizați cadruri precum DSPy pentru a rafina prompturile și logica internă a agentului, utilizând setul de date pentru a conduce îmbunătățiri în precizie și fiabilitate.

VI. Un exemplu ilustrativ al fluxului de lucru

Iată un exemplu simplificat care ilustrează fluxul de lucru recomandat pentru crearea unui agent care apelează API:

Pașul 1: Începeți cu definiții API clare

Imaginați-vă un API pentru gestionarea unei liste de sarcini simple, definit în OpenAPI:

openapi: 3.0.0

info:

titlu: API pentru lista de sarcini

versiune: 1.0.0

căi:

/sarcini:

post:

rezumat: Adăugați o sarcină nouă

corpul cererii:

necesar: adevărat

conținut:

aplicație/json:

schema:

tip: obiect

proprietăți:

descriere:

tip: șir de caractere

răspunsuri:

‘201’:

descriere: Sarcină creată cu succes

get:

rezumat: Obțineți toate sarcinile

răspunsuri:

‘200’:

descriere: Listă de sarcini

Pașul 2: Standardizați accesul la instrumente

Converteți specificația OpenAPI în configurații MCP. Utilizând un instrument precum Stainless.ai, acest lucru ar putea produce:

Pașul 3: Implementați agentul

Utilizând Pydantic pentru modelarea datelor, creați funcții corespunzătoare instrumentelor MCP. Apoi, utilizați un LLM pentru a interpreta interogările în limbaj natural și a selecta instrumentul și parametrii adecvați.

Pașul 4: Curați un set de date de evaluare de calitate

Creați un set de date:

Pașul 5: Optimizați prompturile și logica agentului

Utilizați DSPy pentru a rafina prompturile, concentrându-vă pe instrucțiuni clare, selecția instrumentului și extragerea parametrilor, utilizând setul de date curat pentru evaluare și îmbunătățire.

Prin integrarea acestor blocuri de construcție – de la definiții API structurate și protocoale de instrumente standardizate la practici riguroase de date și optimizare sistematică – echipele de ingineri pot crea agenți care apelează API mai capabili, mai fiabili și mai ușor de întreținut.