Guida alla comprensione, alla costruzione e all’ottimizzazione degli agenti che effettuano chiamate API

Il ruolo dell’Intelligenza Artificiale nelle aziende tecnologiche sta evolvendo rapidamente; i casi d’uso dell’IA sono passati dall’elaborazione passiva delle informazioni a agenti proattivi in grado di eseguire compiti. Secondo un sondaggio condotto da Georgian e NewtonX nel marzo 2025 sulla adozione dell’IA a livello globale, il 91% dei dirigenti tecnici nelle aziende in fase di crescita e nelle imprese sta utilizzando o pianifica di utilizzare l’IA agente.

Gli agenti che effettuano chiamate API sono un esempio primario di questo passaggio agli agenti. Gli agenti che effettuano chiamate API sfruttano i Large Language Model (LLM) per interagire con i sistemi software tramite le loro Interfacce di Programmazione delle Applicazioni (API).

Ad esempio, traducendo i comandi in linguaggio naturale in chiamate API precise, gli agenti possono recuperare dati in tempo reale, automatizzare compiti di routine o anche controllare altri sistemi software. Questa capacità trasforma gli agenti IA in intermediari utili tra l’intento umano e la funzionalità del software.

Le aziende stanno attualmente utilizzando gli agenti che effettuano chiamate API in vari domini, tra cui:

• Applicazioni per i consumatori: gli assistenti come Siri di Apple o Alexa di Amazon sono stati progettati per semplificare le attività quotidiane, come il controllo dei dispositivi smart home e la prenotazione.
• Flussi di lavoro aziendali: le imprese hanno distribuito agenti API per automatizzare compiti ripetitivi come il recupero di dati da CRM, la generazione di report o la consolidazione di informazioni da sistemi interni.
• Raccolta e analisi dei dati: le imprese stanno utilizzando gli agenti API per semplificare l’accesso a set di dati proprietari, risorse basate su abbonamento e API pubbliche al fine di generare informazioni.

In questo articolo, userò un approccio centrato sull’ingegneria per comprendere, costruire e ottimizzare gli agenti che effettuano chiamate API. Il materiale in questo articolo si basa in parte sulla ricerca e sullo sviluppo pratico condotti dal Georgian’s AI Lab. La domanda motivante per gran parte della ricerca del AI Lab nell’area degli agenti che effettuano chiamate API è stata: “Se un’organizzazione ha un’API, qual è il modo più efficace per costruire un agente che possa interfacciarsi con quell’API utilizzando il linguaggio naturale?”

Spiegherò come funzionano gli agenti che effettuano chiamate API e come progettare e ingegnerizzare con successo questi agenti per le prestazioni. Infine, fornirò un flusso di lavoro sistematico che i team di ingegneria possono utilizzare per implementare gli agenti che effettuano chiamate API.

I. Definizioni chiave:

• API o Interfaccia di Programmazione delle Applicazioni: un set di regole e protocolli che consentono a diverse applicazioni software di comunicare e scambiare informazioni.
• Agente: un sistema di intelligenza artificiale progettato per percepire il suo ambiente, prendere decisioni e intraprendere azioni per raggiungere obiettivi specifici.
• Agente che effettua chiamate API: un agente di intelligenza artificiale specializzato che traduce istruzioni in linguaggio naturale in chiamate API precise.
• Agente di generazione di codice: un sistema di intelligenza artificiale che assiste nello sviluppo del software scrivendo, modificando e debuggando il codice. Sebbene sia correlato, il mio focus qui è principalmente sugli agenti che effettuano chiamate API, sebbene l’IA possa anche aiutare a costruire questi agenti.
• MCP (Model Context Protocol): un protocollo, notevolmente sviluppato da Anthropic, che definisce come i LLM possano connettersi e utilizzare strumenti e fonti di dati esterni.

II. Compito principale: tradurre il linguaggio naturale in azioni API

La funzione fondamentale di un agente che effettua chiamate API è interpretare una richiesta in linguaggio naturale dell’utente e convertirla in una o più chiamate API precise. Questo processo solitamente coinvolge:

1. Riconoscimento dell’intento: comprendere l’obiettivo dell’utente, anche se espresso in modo ambiguo.
2. Selezione dello strumento: identificare il punto di terminazione API appropriato (o “strumento”) da un set di opzioni disponibili che può soddisfare l’intento.
3. Estrazione dei parametri: identificare ed estrarre i parametri necessari per la chiamata API selezionata (o chiamate) dalla query dell’utente.
4. Esecuzione e generazione della risposta: effettuare la chiamata API, ricevere la risposta e quindi sintetizzare queste informazioni in una risposta coerente o eseguire un’azione successiva.

Considera una richiesta come “Ehi Siri, com’è il meteo oggi?” L’agente deve identificare la necessità di chiamare un’API meteo, determinare la posizione attuale dell’utente (o consentire la specifica di una posizione) e quindi formulare la chiamata API per recuperare le informazioni meteo.

Per la richiesta “Ehi Siri, com’è il meteo oggi?”, una possibile chiamata API potrebbe essere:

GET /v1/meteo?località=New%20York&unità=metrico

Le sfide iniziali a livello di alto livello sono innate in questo processo di traduzione, tra cui l’ambiguità del linguaggio naturale e la necessità per l’agente di mantenere il contesto attraverso interazioni multi-step.

Ad esempio, l’agente deve spesso “ricordare” parti precedenti di una conversazione o risultati di chiamate API precedenti per informare le azioni attuali. La perdita di contesto è un modo comune di fallimento se non gestito esplicitamente.

III. Progettazione della soluzione: componenti chiave e protocolli

Costruire agenti che effettuano chiamate API efficaci richiede un approccio architettonico strutturato.

1. Definizione degli “strumenti” per l’agente

Perché un LLM possa utilizzare un’API, le capacità di quell’API devono essere descritte in un modo che possa comprendere. Ogni endpoint API o funzione è spesso rappresentato come uno “strumento”. Una definizione di strumento robusta include:

• Una descrizione chiara e in linguaggio naturale dello scopo e della funzionalità dello strumento.
• Una specifica precisa dei parametri di input (nome, tipo, se è richiesto o facoltativo e una descrizione).
• Una descrizione dell’output o dei dati restituiti dallo strumento.

2. Il ruolo del Model Context Protocol (MCP)

MCP è un fattore di abilitazione critico per un utilizzo più standardizzato e robusto degli strumenti da parte dei LLM. Fornisce un formato strutturato per definire come i modelli possano connettersi a strumenti e fonti di dati esterni.

La standardizzazione di MCP è benefica perché consente un’integrazione più facile di strumenti diversi, promuove la riutilizzabilità delle definizioni degli strumenti tra agenti o modelli diversi. Inoltre, è una best practice per i team di ingegneria, iniziando con specifiche API ben definite, come una specifica OpenAPI. Strumenti come Stainless.ai sono progettati per aiutare a convertire queste specifiche OpenAPI in configurazioni MCP, semplificando il processo di rendere le API “pronte per l’agente”.

3. Framework di agenti e scelte di implementazione

Esistono diversi framework che possono aiutare nella costruzione dell’agente stesso. Tra questi:

• Pydantic: sebbene non sia esclusivamente un framework di agenti, Pydantic è utile per definire strutture di dati e garantire la sicurezza dei tipi per input e output degli strumenti, il che è importante per l’affidabilità. Molti implementazioni di agenti personalizzati sfruttano Pydantic per questa integrità strutturale.
• mcp_agent di LastMile: questo framework è progettato specificamente per lavorare con MCP, offrendo una struttura più opinata che si allinea con le pratiche per la costruzione di agenti efficaci come descritto nella ricerca di luoghi come Anthropic.
• Framework interno: è anche sempre più comune utilizzare agenti di generazione di codice AI (utilizzando strumenti come Cursor o Cline) per aiutare a scrivere il codice boilerplate per l’agente, i suoi strumenti e la logica circostante. L’esperienza del Georgian’s AI Lab lavorando con aziende su implementazioni di agenti mostra che questo può essere utile per creare framework personalizzati minimi.

IV. Ingegneria per l’affidabilità e le prestazioni

Garantire che un agente effettui chiamate API in modo affidabile e performante richiede uno sforzo ingegneristico mirato. Due modi per farlo sono (1) la creazione e la convalida del set di dati e (2) l’ingegneria e l’ottimizzazione dei prompt.

1. Creazione e convalida del set di dati

La formazione (se applicabile), il test e l’ottimizzazione di un agente richiedono un set di dati di alta qualità. Questo set di dati dovrebbe consistere in query in linguaggio naturale rappresentative e relative sequenze di chiamate API desiderate o risultati.

• Creazione manuale: la creazione manuale di un set di dati garantisce precisione e rilevanza, ma può essere laboriosa.
• Generazione sintetica: la generazione di dati in modo programmatico o utilizzando LLM può scalare la creazione del set di dati, ma questo approccio presenta sfide significative. La ricerca del Georgian AI Lab ha scoperto che garantire la correttezza e la complessità realistica delle chiamate API e delle query generate sinteticamente è molto difficile. Spesso, le domande generate erano troppo banali o impossibilmente complesse, rendendo difficile misurare le prestazioni dell’agente in modo sfumato. La convalida attenta dei dati sintetici è assolutamente critica.

Per una valutazione critica, un set di dati più piccolo, di alta qualità e verificato manualmente spesso fornisce informazioni più affidabili rispetto a un set di dati sintetico grande e rumoroso.

2. Ingegneria e ottimizzazione dei prompt

Le prestazioni di un agente basato su LLM sono fortemente influenzate dai prompt utilizzati per guidare il suo ragionamento e la selezione degli strumenti.

• Un prompt efficace coinvolge la definizione chiara del compito dell’agente, la fornitura di descrizioni degli strumenti disponibili e la strutturazione del prompt per incoraggiare l’estrazione precisa dei parametri.
• L’ottimizzazione sistematica utilizzando framework come DSPy può migliorare notevolmente le prestazioni. DSPy consente di definire i componenti dell’agente (ad esempio, moduli per la generazione di pensieri, la selezione degli strumenti, la formattazione dei parametri) e quindi utilizza un approccio simile a un compilatore con pochi esempi del set di dati per trovare prompt o configurazioni ottimizzati per questi componenti.

V. Un percorso raccomandato per agenti API efficaci

Sviluppare agenti AI robusti che effettuano chiamate API è una disciplina ingegneristica iterativa. Sulla base dei risultati della ricerca del Georgian AI Lab, i risultati possono essere migliorati notevolmente utilizzando un flusso di lavoro sistematico come il seguente:

1. Inizia con definizioni API chiare: inizia con specifiche API ben strutturate, come specifiche OpenAPI per le API con cui l’agente interagirà.
2. Standardizza l’accesso agli strumenti: converte le tue specifiche OpenAPI in MCP. Strumenti come Stainless.ai possono facilitare questo processo, creando un modo standardizzato per il tuo agente per comprendere e utilizzare le tue API.
3. Implementa l’agente: scegli un framework o un approccio appropriato. Ciò potrebbe coinvolgere l’utilizzo di Pydantic per la modellazione dei dati all’interno di una struttura di agente personalizzata o l’utilizzo di un framework come LastMile’s mcp_agent che è costruito attorno a MCP.
   • Prima di farlo, considera di connettere l’MCP a uno strumento come Claude Desktop o Cline e utilizzarlo manualmente per capire quanto bene un agente generico possa utilizzarlo, quanti iterazioni solitamente richiede per utilizzare l’MCP correttamente e qualsiasi altro dettaglio che potrebbe risparmiare tempo durante l’implementazione.
4. Cura un set di dati di valutazione di qualità: crea manualmente o convalida attentamente un set di dati di query e interazioni API desiderate. Ciò è critico per test e ottimizzazione affidabili.
5. Ottimizza i prompt e la logica dell’agente: utilizza framework come DSPy per raffinare i prompt e la logica interna dell’agente, utilizzando il tuo set di dati per guidare i miglioramenti nell’accuratezza e nell’affidabilità.

VI. Un esempio illustrativo del flusso di lavoro

Ecco un esempio semplificato che illustra il flusso di lavoro raccomandato per la costruzione di un agente che effettua chiamate API:

Fase 1: Inizia con definizioni API chiare

Immagina un’API per la gestione di una semplice lista di attività, definita in OpenAPI:

openapi: 3.0.0

info:

titolo: API della lista di attività

versione: 1.0.0

percorsi:

/attività:

post:

riassunto: Aggiungi un nuovo attività

corpo della richiesta:

richiesto: true

contenuto:

application/json:

schema:

tipo: oggetto

proprietà:

descrizione:

tipo: stringa

risposte:

‘201’:

descrizione: Attività creata con successo

get:

riassunto: Ottieni tutte le attività

risposte:

‘200’:

descrizione: Elenco di attività

Fase 2: Standardizza l’accesso agli strumenti

Converte la specifica OpenAPI in configurazioni del Model Context Protocol (MCP). Utilizzando uno strumento come Stainless.ai, ciò potrebbe produrre:

Fase 3: Implementa l’agente

Utilizzando Pydantic per la modellazione dei dati, crea funzioni corrispondenti agli strumenti MCP. Quindi, utilizza un LLM per interpretare query in linguaggio naturale e selezionare lo strumento e i parametri appropriati.

Fase 4: Cura un set di dati di valutazione di qualità

Crea un set di dati:

Fase 5: Ottimizza i prompt e la logica dell’agente

Utilizza DSPy per raffinare i prompt, concentrandoti su istruzioni chiare, selezione degli strumenti e estrazione dei parametri utilizzando il set di dati curato per la valutazione e il miglioramento.

Integrando questi blocchi costitutivi – dalle definizioni API strutturate e dai protocolli di strumenti standardizzati alle pratiche di dati rigorose e all’ottimizzazione sistematica – i team di ingegneria possono costruire agenti AI che effettuano chiamate API più capaci, affidabili e manutenibili.