Ghid pentru înțelegerea, crearea și optimizarea agenților care apelează API-uri API pentru lista de sarcini version: 1.0.0 paths: /tasks: post: summary: Adăugați o nouă sarcină requestBody: required: true

Rolul Inteligenței Artificiale în companiile tehnologice evoluează rapid; cazurile de utilizare a IA au evoluat de la procesarea 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% din executivii 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-uri sunt un exemplu primar al acestui transfer către agenți. Agenții care apelează API-uri utilizează Modelele Lingvistice Mari (LLM) pentru a interacționa cu sistemele software prin Interfețele lor de Programare a Aplicațiilor (API-uri).

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-uri î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 pentru întreprinderi: Întreprinderile au implementat agenți API pentru a automatiza sarcini repetitive, cum ar fi recuperarea datelor 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 cu abonament și API publice, în scopul de a genera informații.

În acest articol, voi utiliza o abordare centrată pe inginerie pentru a înțelege, crea și optimiza agenții care apelează API-uri. Materialul din acest articol se bazează parțial pe cercetarea și dezvoltarea practică efectuate de Laboratorul de IA al Georgian. Întrebarea care a motivat o parte din cercetarea Laboratorului de IA în domeniul agenților care apelează API-uri a fost: “Dacă o organizație are un API, cea mai eficientă modalitate 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-uri și cum să proiectați și să inginerizați cu succes acești agenți pentru performanță. În cele din urmă, voi furniza un flux de lucru sistematic pe care echipele de inginerie îl pot utiliza pentru a implementa agenții care apelează API-uri.

I. Definiri 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 IA proiectat pentru a-și percepe mediul, a lua decizii și a acționa pentru a atinge obiective specifice.
• Agenț care apelează API-uri: Un agent de IA specializat care traduce instrucțiuni în limbaj natural în apeluri API precise.
• Agenț de generare de cod: Un sistem de IA care asistă în dezvoltarea de software prin scrierea, modificarea și depanarea codului. Deși este legat de subiect, accentul meu aici se pune în principal pe agenții care apelează API-uri, 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 cum modelele LLM pot conecta și utiliza instrumente și surse de date externe.

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

Funcția fundamentală a unui agent care apelează API-uri 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 de terminare al API-ului corespunzător (sau “instrumentului”) dintr-un set de opțiuni disponibile care poate îndeplini intenția.
3. Extracția parametrilor: Identificarea și extragerea parametrilor necesari pentru apelul (apelurile) API selectat(e) din interogarea utilizatorului.
4. Execuție și generare de răspuns: Realizarea 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 recupera 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 ca agenția să mențină contextul pe parcursul interacțiunilor cu mai multe etape.

De exemplu, agenția trebuie adesea să “țină minte” părțile 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 în mod explicit.

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

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

1. Definirea “instrumentelor” pentru agent

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

• O descriere clară și î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 care permite o utilizare mai standardizată și robustă a instrumentelor de către LLM. Acesta oferă un format structurat pentru definirea modului în care modelele pot conecta și utiliza instrumente și surse de date 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 inginerie, î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-urile “gata pentru agenți”.

3. Cadre de agent și alegeri de implementare

Există mai multe cadre care pot ajuta la crearea agenților. Acestea includ:

• Pydantic: Deși nu este exclusiv un cadru de agent, 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 de agenți personalizați utilizează Pydantic pentru această integritate structurală.
• mcp_agent de la LastMile: Acest cadru este proiectat în mod special pentru a lucra cu MCP, oferind o structură mai opinată care se aliniază cu practicile pentru crearea 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 frecvent să se utilizeze agenți de generare de cod IA (utilizând unelte precum Cursor sau Cline) pentru a ajuta la scrierea codului de bază pentru agent, instrumentele sale și logica înconjurătoare. Experiența Laboratorului de IA al Georgian în colaborare cu companii pentru implementări agențiale arată că acest lucru poate fi excelent pentru crearea unor cadre personalizate minimale.

IV. Ingineria pentru fiabilitate și performanță

Asigurarea faptului că un agent realizează apeluri API în mod fiabil și are o bună performanță 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 promtului.

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 corespunzătoare de apeluri API sau rezultate.

• Creare manuală: Crearea 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 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 informații mai fiabile decât unul mare și zgomotos sintetic.

2. Ingineria și optimizarea promtului

Performanța unui agent bazat pe LLM este puternic influențată de promturile 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 cadre precum DSPy poate îmbunătăți semnificativ performanța. DSPy permite definirea componentelor agentului (de exemplu, module pentru generarea de gânduri, selecția instrumentului, formatarea parametrilor) și apoi utilizează o abordare similară unui compilator cu exemple de uzură din setul de date pentru a găsi promturi sau configurații optimizate pentru aceste componente.

V. Un traseu recomandat pentru agenți API eficienți

Dezvoltarea de agenți AI care apelează API-uri robuste este o disciplină inginerească iterativă. Pe baza descoperirilor cercetării Laboratorului de IA al 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 bine structurate pentru API-urile cu care va interacționa agentul.
2. Standardizați accesul la instrumente: Convertește specificațiile OpenAPI în MCP. Unelte precum Stainless.ai pot facilita acest proces, creând o modalitate standardizată pentru ca agentul dvs. să înțeleagă și să utilizeze API-urile.
3. Implementați agentul: Alegeți un cadru sau o abordare adecvată. Acest lucru poate implica utilizarea Pydantic pentru modelarea datelor în cadrul unei structuri de agent personalizat sau utilizarea unui cadru precum mcp_agent de la 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 în mod 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 obișnuite necesită pentru a utiliza MCP corect și orice alte detalii care ar putea economisi timp î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 promturi și logică de agent: Utilizați cadre precum DSPy pentru a rafina promturile și logica internă a agentului, utilizând setul de date pentru a conduce îmbunătățirile î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-uri:

Etapa 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:
application/json:

schema:

type: object

properties:

description:

type: string

responses:

‘201’:

description: Sarcină creată cu succes

get:

summary: Obțineți toate sarcinile

responses:

‘200’:

description: Listă de sarcini

Etapa 2: Standardizați accesul la instrumente

Convertește specificația OpenAPI în configurații Model Context Protocol (MCP). Utilizând un instrument precum Stainless.ai, acest lucru ar putea produce:

Etapa 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ări în limbaj natural și selectați instrumentul și parametrii corespunzători.

Etapa 4: Curați un set de date de evaluare de calitate

Creați un set de date:

Etapa 5: Optimizați promturi și logică de agent

Utilizați DSPy pentru a rafina promturile, 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 de date riguroase și optimizare sistematică – echipele de inginerie pot crea agenți AI care apelează API-uri mai capabili, mai fiabili și mai ușor de întreținut.