OpenAPI per gli agenti IA
Un documento OpenAPI descrive un’API HTTP in forma leggibile dalle macchine: i suoi endpoint, i parametri accettati da ciascuno, la struttura di ogni risposta e il metodo di autenticazione. Un agente può leggerlo per imparare a chiamare un’API che non ha mai visto.
- Servizi in elenco con una descrizione OpenAPI
- 23
- Siti che forniscono un ai-plugin.json reale
- 75 su 1504
Da una descrizione dell’API agli strumenti
I framework per agenti e diverse piattaforme di assistenti possono trasformare le operazioni di un documento OpenAPI in strumenti: l’identificativo dell’operazione diventa il nome dello strumento, il riepilogo e la descrizione indicano al modello quando usarlo, e lo schema dei parametri diventa l’input dello strumento. Il modello compila poi i parametri e la piattaforma esegue la richiesta HTTP.
Il manifest del plugin
Il manifest /.well-known/ai-plugin.json è stato introdotto con il sistema di plugin di ChatGPT nel 2023: indicava il nome del servizio, lo descriveva per il modello e rimandava a un documento OpenAPI. Quel sistema di plugin è stato poi sostituito, ma alcuni siti forniscono ancora il file, che indica ancora dove si trova la loro descrizione dell’API.
OpenAPI e MCP
OpenAPI descrive qualsiasi API HTTP, chiunque la chiami. MCP è un protocollo pensato per gli assistenti: il server elenca i propri strumenti quando il client si collega, e il client li chiama. Molti server MCP sono un sottile strato sopra un’API che ha anche una descrizione OpenAPI, ed esistono strumenti che generano l’uno dall’altra.
Cosa rende una descrizione adatta agli agenti
Identificativi e descrizioni delle operazioni chiari, scritti per chi non ha mai visto l’API; esempi; enumerazioni per i valori ammessi; errori documentati; lo schema di autenticazione dichiarato, non solo spiegato a parole; e operazioni piccole, ciascuna con un solo compito. Un URL pubblicato e stabile per il documento permette ad agenti e directory di trovarlo.
Servizi con una descrizione OpenAPI · Servizi con un’API pubblica · Sfoglia la directory →
Altri approfondimenti: Che cos’è un server MCP? · Che cos’è llms.txt? · Come gli assistenti IA trovano e prenotano viaggi · Come vengono verificate le schede · Trasporti MCP: stdio, Streamable HTTP e SSE · Server MCP remoto o locale: quale usare · Come aggiungere un server MCP a un assistente IA · Che cos’è il MCP Registry ufficiale? · Cosa contiene un file llms.txt · Come gli assistenti IA trovano la disponibilità per i viaggi · Prima di collegare un server MCP: una checklist