Guida per comprendere, costruire e ottimizzare gli agenti che chiamano API API della lista di attività version: 1.0.0 paths: /tasks: post: riassunto: Aggiungi una nuova 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à Passo 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: Nome dello strumento Descrizione Parametri di input Descrizione dell’output Aggiungi attività Aggiunge una nuova attività alla lista di attività. `descrizione` (stringa, richiesta): la descrizione dell’attività. Conferma della creazione dell’attività. Ottieni attività Recupera tutte le attività dalla lista di attività. Nessuno Un elenco di attività con le loro descrizioni. Passo 3: Implementa l’agente Utilizzando Pydantic per la modellazione dei dati, crea funzioni corrispondenti agli strumenti MCP. Quindi, utilizza un LLM per interpretare le query in linguaggio naturale e selezionare lo strumento e i parametri appropriati. Passo 4: Cura un set di dati di valutazione di alta qualità Crea un set di dati: Query Chiamata API attesa Risultato atteso “Aggiungi ‘Acquista generi alimentari’ alla mia lista.” `Aggiungi attività` con `descrizione` = “Acquista generi alimentari” Conferma della creazione dell’attività. “Cosa c’è nella mia lista?” `Ottieni attività` Elenco di attività, inclusa “Acquista generi alimentari”. Passo 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 API-calling più capaci, affidabili e manutenibili.

Il ruolo dell’Intelligenza Artificiale nelle aziende tecnologiche sta evolvendo rapidamente; i casi d’uso dell’AI sono passati dall’elaborazione passiva delle informazioni all’esecuzione di compiti proattivi. Secondo un sondaggio condotto da Georgian e NewtonX nel marzo 2025, il 91% degli executive tecnici nelle aziende in fase di crescita e nelle imprese stanno utilizzando o pianificano di utilizzare l’AI agente.

Gli agenti che chiamano API sono un esempio primario di questo passaggio agli agenti. Gli agenti che chiamano 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 attività ripetitive o addirittura controllare altri sistemi software. Questa capacità trasforma gli agenti AI in intermediari utili tra l’intento umano e la funzionalità del software.

Le aziende stanno attualmente utilizzando gli agenti che chiamano 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 e la prenotazione di appuntamenti.
• Flussi di lavoro aziendali: le imprese hanno distribuito agenti API per automatizzare attività ripetitive come il recupero di dati da CRM, la generazione di report o la consolidazione di informazioni da sistemi interni.
• Recupero e analisi dei dati: le imprese stanno utilizzando gli agenti API per semplificare l’accesso ai set di dati proprietari, alle risorse basate su abbonamento e alle API pubbliche al fine di generare informazioni.

In questo articolo, userò un approccio ingegneristico per comprendere, costruire e ottimizzare gli agenti che chiamano API. Il materiale di questo articolo si basa in parte sulla ricerca e sullo sviluppo pratico condotti dal Georgian AI Lab. La domanda motivante per gran parte della ricerca del Georgian AI Lab nel campo degli agenti che chiamano 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 chiamano API e come progettare e ingegnerizzare questi agenti per le prestazioni. Infine, fornirò un flusso di lavoro sistematico che i team di ingegneria possono utilizzare per implementare gli agenti che chiamano 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 compiere azioni per raggiungere obiettivi specifici.
• Agente che chiama 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 aiuta nello sviluppo del software scrivendo, modificando e debuggando il codice. Sebbene sia correlato, il mio focus qui è principalmente sugli agenti che chiamano API, sebbene l’AI possa anche aiutare a costruire questi agenti.
• MCP (Model Context Protocol): un protocollo, in particolare sviluppato da Anthropic, che definisce come i LLM possano connettersi a strumenti e fonti di dati esterni.

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

La funzione fondamentale di un agente che chiama 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 dell’API appropriato (o “strumento”) da un set di opzioni disponibili che possono 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 tempo oggi?” L’agente deve identificare la necessità di chiamare un’API del tempo, determinare la posizione attuale dell’utente (o consentire la specifica di una posizione) e quindi formulare la chiamata API per recuperare le informazioni sul tempo.

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

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

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 chiamano 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 il modello possa comprendere. Ogni punto di terminazione dell’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 opzionale e una descrizione).
• Una descrizione dell’output o dei dati che lo strumento restituisce.

2. Il ruolo del Model Context Protocol (MCP)

MCP è un fattore abilitante critico per un uso 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 diversi agenti o modelli. Inoltre, è una best practice per i team di ingegneria, a partire da specifiche API ben definite, come una specifica OpenAPI. Gli 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 agente e scelte di implementazione

Ci sono diversi framework che possono aiutare nella costruzione dell’agente stesso. Tra questi ci sono:

• Pydantic: sebbene non sia esclusivamente un framework di agente, Pydantic è utile per definire strutture di dati e garantire la sicurezza dei tipi per gli input e gli output degli strumenti, il che è importante per l’affidabilità. Molti agenti personalizzati sfruttano Pydantic per questa integrità strutturale.
• Agente mcp di LastMile: questo framework è progettato specificamente per funzionare con i protocolli 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 gli 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 AI Lab nel lavorare con le aziende sulle implementazioni agente mostra che ciò può essere ottimo 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 nelle 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 i 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 dei parametri precisa.
• 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 gli agenti API efficaci

Sviluppare agenti API-calling AI robusti è 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 OpenAPI ben strutturate per le API con cui l’agente interagirà.
2. Standardizza l’accesso agli strumenti: converte le tue specifiche OpenAPI in MCP. Gli 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 Agente mcp di LastMile che è costruito intorno ai protocolli MCP.
   • Prima di farlo, considera di connettere il protocollo MCP a uno strumento come Claude Desktop o Cline e utilizza manualmente questa interfaccia per capire come un agente generico possa utilizzarlo, quante iterazioni solitamente richiede per utilizzare il protocollo MCP correttamente e qualsiasi altro dettaglio che potrebbe risparmiarti tempo durante l’implementazione.
4. Cura un set di dati di valutazione di alta 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: impiega 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 chiama API:

Passo 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: