API per AI Agent: da MCP a endpoint personalizzati

Quando gli LLM hanno imparato a chiamare funzioni

Nell’era di GPT-3, interagire con un LLM significava fornirgli un prompt e ricevere testo in risposta. La conoscenza del modello era ampia ma statica, congelata in base a ciò che contenevano i dati di addestramento. Potevi chiedergli di spiegare il quantum computing o di scrivere una bozza di email, e avrebbe prodotto testo plausibile. Ma non poteva controllare il meteo di oggi, interrogare un database o compiere alcuna azione nel mondo reale.

La funzionalità che ha cambiato tutto questo riceve sorprendentemente poco credito. Ha dato al modello una scelta tra generare testo e chiamare una funzione. Invece di produrre sempre il token successivo, il modello poteva ora emettere un oggetto JSON strutturato che specificava il nome di una funzione e i suoi argomenti. Il runtime avrebbe eseguito quella funzione, restituito il risultato al modello, e il modello avrebbe continuato da lì. Il paper ReAct (Yao et al., 2022) ha formalizzato questo schema come loop Thought-Action-Observation. Il modello ragiona su cosa fare, compie un’azione (chiama uno strumento), osserva il risultato e ripete. Ogni AI agent serio nel 2026 funziona su una qualche versione di questo pattern.

Il loop

Claude Code, OpenClaw, Codex, Devin e decine di altri sistemi agentici funzionano tutti nello stesso modo. Chiama uno strumento, osserva il risultato, decide cosa fare dopo, ripeti. Simon Willison lo ha espresso bene: “Un agent LLM esegue strumenti in un loop per raggiungere un obiettivo.”

Claude Code, per esempio, usa un master loop single-threaded senza sciami multi-agent o grafi di orchestrazione complessi: while(tool_call) -> execute -> feed results -> repeat.

La ricerca di Anthropic sull’autonomia degli agent mostra che le durate dei turni in Claude Code sono quasi raddoppiate in tre mesi, passando da 25 a oltre 45 minuti. Gli utenti si fidano sempre di più del loop quando funziona in autonomia. I dati mostrano che gli utenti esperti interrompono più spesso (passando dall’approvazione per singola azione al monitoraggio strategico), mentre l’agent stesso chiede chiarimenti più del doppio delle volte rispetto a quelle in cui gli utenti lo interrompono.

Questo pattern di loop compare ovunque, negli agent di coding, nei bot di assistenza clienti e nei controller robotici.

Che cosa conta come strumento?

Gli LLM ci danno una notevole libertà nel decidere a quale livello di astrazione debba operare uno strumento. A un estremo, hai endpoint API altamente specifici: “crea un contatto HubSpot con questi 12 campi.” All’altro, hai strumenti come “esegui questo comando bash” o “esegui questo codice Python”, che sono essenzialmente “fai quello che vuoi.”

Devin opera con tre strumenti: shell, editor di codice, browser. Anche lo strumento principale di Claude Code è una shell. OpenClaw usa un sistema dinamico di plugin per skill. La tendenza negli strumenti di coding agentico è stata verso meno strumenti, più generali, invece che molti strumenti specifici.

Simon Willison ha osservato che MCP “inizialmente è esploso, ma poi è sembrato meno centrale” per gli agent di coding perché bash è lo strumento universale. File e script sono primitive con overhead inferiore rispetto a implementazioni complete di server MCP. Se l’agent può scrivere ed eseguire codice, può fare quasi tutto senza avere bisogno di una definizione di strumento dedicata.

Ma gli strumenti general-purpose funzionano per agent general-purpose. Per AI agent specifici di dominio (assistenza clienti, vendite, operazioni interne), ti servono strumenti specifici di dominio. Il tuo agent di supporto non dovrebbe scrivere Python per controllare lo stato di un ordine. Dovrebbe chiamare un endpoint API ben definito, con parametri chiari e risposte prevedibili. La progettazione del tuo set di strumenti diventa una decisione di prodotto.

Che cosa significa oggi un endpoint API

Per gli AI agent, un endpoint API funziona come una dichiarazione di capacità. Pubblicarne uno significa che tu (o il tuo AI agent) puoi ora fare qualcosa che prima non era possibile.

Questo funziona in entrambe le direzioni. Un fornitore software pubblica un’API in modo che altri possano integrarsi con il suo prodotto. Ma un AI agent può anche scoprire endpoint autonomamente cercando nella documentazione, leggendo specifiche OpenAPI o letteralmente cercando su Google come svolgere un’attività.

Un server MCP è un bundle curato di endpoint API con un’idea predefinita di come dovrebbero essere usati. Chi crea l’MCP ha già preso decisioni su quali endpoint esporre, come nominarli, quali parametri rendere disponibili e, implicitamente, quali workflow supportare. Questa cura è sia il punto di forza (comodità, standardizzazione) sia il punto debole (rigidità, perimetro opinabile). Il server di Notion è un esempio concreto: pubblica 28 strumenti, e a un agent per help center ne servono quattro, distribuiti su due connessioni.

Gli MCP scambiano controllo con facilità d’uso. Nel 2026, l’AI scrive la maggior parte del codice di integrazione. Se un agent può leggere la documentazione API e scrivere da solo l’integrazione, l’argomento della “facilità d’uso” a favore di MCP diventa più debole. Il livello MCP potrebbe contare soprattutto durante il periodo di transizione, mentre gli strumenti non hanno ancora raggiunto le capacità del modello. La guida di Anthropic sui pattern di progettazione per l’uso degli strumenti è un riferimento pratico per strutturare gli schemi degli strumenti, indipendentemente dal fatto che tu usi MCP o endpoint individuali.

Uno sviluppo correlato: llms.txt è uno standard proposto in cui i siti web pubblicano un file /llms.txt per indirizzare i modelli AI verso risorse ad alto valore. Anthropic, Cloudflare, Docker e Stripe lo hanno adottato. MCP standardizza l’invocazione degli strumenti; llms.txt standardizza la scoperta della documentazione. Entrambi cercano di rendere il web più leggibile per le macchine, da angolazioni diverse.

Che cos’è un endpoint API nel contesto degli AI agent?

Un endpoint API è un URL specifico che accetta input strutturato e restituisce output strutturato. Per gli AI agent, ogni endpoint rappresenta una capacità distinta, qualcosa che l’agent può fare nel mondo reale. La descrizione dell’endpoint, le definizioni dei parametri e le risposte di errore servono come manuale di istruzioni dell’agent. Quanto meglio è documentato l’endpoint, tanto più affidabilmente un agent può usarlo.

A differenza degli sviluppatori umani, che possono leggere tutorial ed eseguire debug in modo iterativo, un agent si affida allo schema e alla descrizione dell’endpoint per effettuare una singola chiamata corretta. Per questo la documentazione API progettata per il consumo da parte dell’AI conta più che mai. Solo il 24% degli sviluppatori oggi progetta API pensando agli AI agent, nonostante l’89% usi l’AI nel proprio workflow.

Che cos’è MCP (Model Context Protocol)?

MCP è un protocollo aperto introdotto da Anthropic che standardizza il modo in cui gli AI agent si connettono a strumenti esterni e origini dati. Pensalo come l’USB-C per l’AI. Un singolo connettore che qualsiasi fornitore di strumenti può implementare e qualsiasi AI agent può consumare. Un server MCP espone un insieme di strumenti (essenzialmente endpoint API) con schemi standardizzati, e un client MCP (l’agent) può scoprirli e chiamarli senza codice di integrazione personalizzato. Per una spiegazione tecnica più approfondita, consulta il nostro post MCP Explained. Per un resoconto pratico di MCP in produzione, consulta la nostra analisi delle sfide reali nella costruzione su MCP di Shopify.

Lo spettro del controllo in Quickchat AI

Quickchat AI ti offre tre modi per dotare un AI Agent di strumenti esterni. Si collocano su uno spettro che va dal più automatizzato al più controllato. Ogni approccio fa un compromesso diverso tra velocità di configurazione e precisione del comportamento.

Remote MCP: collega e parti

Remote MCP è il modo più rapido per collegare un AI Agent a funzionalità esterne. Fornisci l’URL di un server MCP, Quickchat AI si connette, scopre tutti gli strumenti disponibili e ti consente di selezionare quali deve usare il tuo agent.

Come configurarlo:

1. Vai in AI Actions nella dashboard di Quickchat AI
2. Fai clic su “Add Remote MCP”
3. Incolla l’URL del tuo server MCP (ad esempio, https://mcp.example.com/sse)
4. Facoltativamente aggiungi un token di autenticazione o header personalizzati (le due opzioni si escludono a vicenda)
5. Fai clic su “Connect.” Quickchat AI scopre tutti gli strumenti disponibili e ne mostra i nomi
6. Attiva o disattiva i singoli strumenti per controllare quali può usare il tuo agent
7. Imposta il flag “default tool is active” per controllare se gli strumenti appena scoperti vengono abilitati o disabilitati automaticamente

Che cosa succede sotto il cofano:

Quando fai clic su Connect, Quickchat AI rileva automaticamente il protocollo di trasporto dall’URL. Se l’URL contiene sse, viene usato il trasporto SSE; altrimenti streamable_http è il valore predefinito. Quando fornisci un token di autenticazione, viene inviato come token Bearer nell’header Authorization.

Il filtro degli strumenti funziona tramite un sistema a tre livelli. Ogni strumento del server MCP viene controllato rispetto a due insiemi: gli strumenti abilitati esplicitamente sono sempre inclusi, gli strumenti disabilitati esplicitamente sono sempre esclusi, e qualsiasi strumento non presente in nessuno dei due insiemi ricade sull’impostazione “default tool is active” che hai scelto. Questo significa che quando un server MCP aggiunge nuovi strumenti, controlli se sono automaticamente disponibili per il tuo agent o se richiedono un’attivazione esplicita.

A runtime, quando inizia una conversazione, vengono caricate tutte le connessioni Remote MCP attive per l’agent. Gli strumenti vengono recuperati e filtrati in base alla configurazione di ciascuna connessione, e l’univocità dei nomi degli strumenti viene verificata su tutte le origini (con un avviso se vengono trovati duplicati).

Il compromesso: ottieni accesso immediato a tutto ciò che l’MCP espone, ma hai controllo limitato su descrizioni degli strumenti, definizioni dei parametri o sul modo in cui l’agent decide di usarli. Come abbiamo riscontrato quando abbiamo costruito un AI Agent su MCP di Shopify, passare dalla demo alla produzione richiede una messa a punto attenta che l’approccio in bundle di MCP può rendere difficile.

Vedi anche: collega il tuo agent a un server MCP remoto, How to Launch Your Quickchat AI MCP, considerazioni sulla sicurezza MCP, documentazione Quickchat AI: canale MCP.

AI Actions (HTTP Request): un endpoint, controllo completo

Una AI Action in Quickchat AI è un singolo endpoint API HTTP che configuri individualmente per il tuo AI Agent. Dove MCP importa un bundle di strumenti in una sola volta, ogni AI Action ti dà pieno controllo su una specifica capacità. Per un esempio completo svolto, quattro azioni che creano e arricchiscono contatti, registrano deal e aprono ticket in un CRM, consulta il tutorial HubSpot AI Actions.

Configurare una AI Action:

1. Name (max 64 caratteri): diventa il nome dello strumento visto dall’LLM. Viene normalizzato in un identificatore valido (ad esempio, “Check Order Status” diventa Check_Order_Status)
2. Description (max 1.000 caratteri): è il campo più importante. La descrizione dice all’LLM quando usare questo strumento. Buone descrizioni specificano in quali circostanze conversazionali chiamarlo, quali informazioni raccogliere prima dall’utente e come comunicare i risultati
3. HTTP method: GET, POST, PATCH, DELETE o PUT
4. URL (max 10.000 caratteri): può contenere placeholder {{parameter_name}} per valori dinamici
5. Headers: coppie chiave-valore per autenticazione e content type
6. Body items / Body JSON: corpo della richiesta con iniezione dei parametri
7. Query parameters: valori della query string URL
8. Parameters (max 10): ciascuno con un nome, una descrizione (max 500 caratteri), un tipo (str, int, float, bool o custom), un flag required e un valore predefinito opzionale

I placeholder {{parameter_name}} sono il meccanismo chiave. Quando l’LLM chiama lo strumento, fornisce valori per ogni parametro in base al contesto della conversazione. Quickchat AI inietta poi quei valori nei template di URL, header, body e query string prima di effettuare la richiesta HTTP. Esistono anche quattro variabili integrate che possono essere iniettate in questo modo: scenario_id, conversation_id, conversation_channel e conversation_url.

Una AI Action configurata per controllare lo stato di un ordine, con template URL con placeholder di parametro, header e definizioni dei parametri.

Sotto il cofano: Quickchat AI costruisce dinamicamente uno schema tipizzato dalle tue definizioni dei parametri per ogni AI Action. I cinque tipi supportati (str, int, float, bool, custom) vengono mappati ai rispettivi equivalenti nativi, e questo schema viene usato per validare gli input dell’LLM prima di effettuare la richiesta HTTP.

Un esempio di AI Action per controllare lo stato di un ordine:

{
  "name": "check_order_status",
  "description": "Quando l'utente chiede informazioni sullo stato del suo ordine e ha fornito un numero d'ordine, chiama questo endpoint per recuperare lo stato attuale. Riporta all'utente lo stato, la data di consegna stimata e il numero di tracking (se disponibile).",
  "method": "GET",
  "url": "https://api.example.com/orders/{{order_id}}",
  "headers": [
    { "name": "Authorization", "value": "Bearer YOUR_API_KEY" },
    { "name": "Content-Type", "value": "application/json" }
  ],
  "parameters": [
    {
      "name": "order_id",
      "description": "L'ID ordine fornito dall'utente (ad esempio, ORD-12345)",
      "type": "str",
      "is_required": true
    }
  ]
}

Test: La dashboard ha un pulsante “Test” che ti permette di fornire valori di parametro di esempio e vedere la richiesta HTTP effettiva (incluso un comando curl generato) e la risposta prima del deploy.

Suggerimenti per scrivere descrizioni AI Action efficaci:

• Sii specifico su quando l’agent deve chiamarla: “Quando l’utente chiede informazioni sullo stato del suo ordine e fornisce un numero d’ordine, chiama questo endpoint”
• Indica quali informazioni raccogliere prima: “Prima della chiamata, assicurati di avere l’indirizzo email dell’utente e l’ID ordine”
• Descrivi come gestire la risposta: “Se lo stato è ‘spedito’, comunica all’utente il numero di tracking presente nella risposta”
• Per workflow multi-step, descrivi la sequenza nel prompt di sistema principale dell’agent invece che nelle descrizioni delle singole azioni, e per trasferire un valore tra azioni e subordinare la scrittura a quel valore, usa Save to memory più una run-condition

Un esempio svolto: per una AI Action passo passo che registra lead, domande senza risposta e richieste di demo direttamente in un foglio di calcolo, consulta come collegare un AI agent a Google Sheets.

Generate from Text: lascia che sia l’AI a capirlo

La terza opzione è per gli utenti che sanno cosa vogliono che faccia il proprio agent, ma non sanno quale endpoint API (o persino quale servizio) usare.

Come funziona:

1. Digiti una descrizione in linguaggio naturale di ciò che vuoi, ad esempio, “Voglio che il mio AI Agent sia in grado di avviare la Tesla di un utente quando lo chiede”
2. Quickchat AI la invia a un LLM con lo strumento web_search abilitato
3. Il modello effettua ricerche sul web per trovare l’API corretta, legge la documentazione ufficiale e genera una specifica completa di AI Action, inclusi URL, metodo, header, parametri e requisiti di autenticazione
4. Il risultato ritorna con la configurazione completa dell’azione, citazioni della documentazione usata e un messaggio esplicativo che annota assunzioni e lacune
5. Tu controlli, inserisci le tue credenziali e attivi

Inserimento di una descrizione in linguaggio naturale della capacità desiderata.

La configurazione AI Action generata con citazioni della documentazione API usata.

La generazione automatizzata di AI Action è strutturata attorno a tre priorità:

• Priorità 1: comprendere l’intento. Identificare la capacità esatta che lo sviluppatore vuole e lo specifico endpoint API che la fornisce
• Priorità 2: basarsi sulla documentazione. Usare la ricerca web per trovare documentazione ufficiale del fornitore, non ipotesi
• Priorità 3: progettare semantica conversation-first. Il nome e la descrizione generati dovrebbero riguardare quando in una conversazione viene usato questo strumento, non solo ciò che l’API fa tecnicamente

Il prompt usa due convenzioni per i placeholder. {{param}} indica parametri di runtime che l’LLM compila dal contesto della conversazione. [[secret_name]] (doppie parentesi quadre) indica costanti dello sviluppatore come chiavi API e ID account che devono essere configurate manualmente prima dell’attivazione. Ogni nome di parametro deve comparire come placeholder {{that_exact_name}} da qualche parte nella definizione della richiesta, e non sono consentiti placeholder orfani.

Il sistema usa una policy fail-closed. Se il modello non può confermare dalla documentazione un’informazione critica (il metodo HTTP, l’URL, lo schema di autenticazione o la struttura del payload richiesta), non viene creata alcuna azione. Il sistema restituisce invece una spiegazione concisa di ciò che manca, anziché tirare a indovinare.

Qui il punto filosofico sugli AI agent che scoprono API si collega a una funzionalità di prodotto concreta. La funzionalità Generate from Text è letteralmente un AI agent (un LLM con ricerca web) che costruisce una definizione di strumento per un altro AI agent (l’agent Quickchat AI che lo userà nelle conversazioni).

Un esempio svolto: per il tutorial completo che trasforma due frasi digitate in due azioni live e testate (una ricerca meteo senza chiave e una NASA con chiave, incluso il rifiuto fail-closed), consulta come collegare il tuo AI agent a qualsiasi API in inglese semplice.

A runtime, tutti questi tipi di strumenti vengono assemblati insieme. Quickchat AI raccoglie strumenti AI Action con richiesta HTTP, strumenti Shopify MCP, strumenti di knowledge base, strumenti Remote MCP, strumenti Discord e altri strumenti personalizzati in una raccolta da presentare all’LLM. Il modello non vede alcuna distinzione tra loro. Uno strumento Remote MCP e una AI Action configurata manualmente appaiono identici una volta inseriti nell’elenco degli strumenti.

API aperte come nuova SEO

Se gli AI agent scopriranno e useranno API in modo autonomo, avere un’API ben documentata e facile da usare diventa un asset di distribuzione. Gartner prevede che oltre il 30% dell’aumento della domanda di API proverrà dagli AI agent entro il 2026.

Le aziende che dispongono di API aperte con barriere minime alle credenziali potrebbero scoprire che le loro API diventano il loro miglior canale di acquisizione. Invece delle impressioni nella ricerca Google, le “impressioni” sono AI agent che scelgono di usare il tuo servizio anziché quello di un concorrente.

La stessa logica si applica a un livello superiore. Un AI agent che risponde dalla tua documentazione può a sua volta essere esposto come server MCP che ChatGPT, Claude e Cursor chiamano come strumento, rendendo la tua conoscenza, non solo la tua API, rilevabile dal web agentico.

La qualità della tua documentazione API determina se un AI agent può integrarsi con te con successo al primo tentativo. Descrizioni dei parametri, messaggi di errore e risposte di esempio svolgono la stessa funzione di meta description e dati strutturati nella SEO tradizionale. Una risposta di errore confusa o un campo obbligatorio non documentato significa che un agent fallirà, e dall’altra parte non c’è un umano a fare debug.

Le aziende le cui API non sono documentate o sono bloccate dietro requisiti pesanti di credenziali potrebbero ritrovarsi invisibili al web agentico, nello stesso modo in cui le aziende senza siti web sono diventate invisibili a Google negli anni 2000.

Computer use contro API

Ci sono investimenti significativi nell’insegnare ai modelli AI il “computer use” (fare clic su pulsanti, compilare moduli, navigare UI). Anthropic, OpenAI (Operator) e progetti open-source come Browser Use ne offrono tutti versioni.

Ma l’uso del browser è un workaround per un’API mancante. Una chiamata POST /orders richiede millisecondi e restituisce dati strutturati. Un browser agent che naviga un flusso di checkout richiede minuti e può rompersi quando un pulsante si sposta di tre pixel a sinistra. Le API sono più veloci, più deterministiche e meno costose da eseguire.

La controargomentazione è reale: le API non esistono per tutto. Sistemi legacy, software enterprise senza superficie API, dispositivi fisici controllati tramite GUI. In questi casi il computer use colma una lacuna reale.

La risposta migliore a lungo termine a “non abbiamo un’API per questo” è probabilmente costruire l’API invece di insegnare all’AI a usare la GUI. Man mano che più software viene scritto da AI agent per AI agent, il costo di costruire e mantenere API diminuisce. Il calcolo economico che rendeva più economico fare scraping di una UI rispetto a costruire un’API sta cambiando.

C’è anche un aspetto di sicurezza. La “trifecta letale” di Simon Willison descrive la combinazione pericolosa di accesso a dati privati + esposizione a contenuti non affidabili + comunicazione esterna. Questo vale per entrambi gli approcci, ma gli strumenti basati su API sono più facili da auditare e limitare. Puoi registrare ogni chiamata API, validare ogni parametro e applicare rate limit a ogni endpoint. Fare l’equivalente per un browser agent che può fare clic su qualsiasi cosa è molto più difficile.

Strumenti per il mondo fisico

Tutto ciò che è stato discusso finora riguarda il software. Lo stesso pattern compare nel mondo fisico.

RT-2 e Gemini Robotics di Google DeepMind usano la stessa architettura, tranne per il fatto che gli strumenti inviano comandi ad attuatori invece che ad API. Il framework SPCA (Sense-Plan-Code-Act) formalizza questo schema per la robotica: scansiona l’ambiente, pianifica l’approccio, genera codice eseguibile, eseguilo, osserva i risultati.

Non esiste un’API per “sposta a destra la pianta sulla mia scrivania.” Ma un robot con una fotocamera potrebbe definire al volo move_object(object_id="plant_01", direction="right", distance_cm=15) come strumento e poi chiamarlo. La definizione dello strumento funge da interfaccia tra il livello di ragionamento e il livello di esecuzione fisica, lo stesso ruolo che gli endpoint API svolgono nel software.

L’architettura LLM + strumenti + loop è general-purpose. Oggi è più facile implementarla nel software, ma la robotica sta recuperando.

API scritte dall’AI, per l’AI

In circa due anni (dal 2024 al 2026), siamo passati dalla maggior parte del codice scritto da esseri umani alla maggior parte del codice scritto dall’AI. È un buon momento per riconsiderare che cosa sia un endpoint API. Sempre più spesso, un endpoint è una dichiarazione di capacità progettata per essere scoperta ed eseguita da macchine, non un’interfaccia tecnica su cui gli sviluppatori umani leggono documentazione per poi integrarla manualmente.

Gli MCP sono un livello di standardizzazione utile, ma sono anche un livello di curatela che introduce bias. Chi crea l’MCP decide quali strumenti esporre e come inquadrarli. Per gli AI agent in produzione, quell’inquadramento potrebbe non corrispondere a ciò di cui hai effettivamente bisogno. (Ne abbiamo scritto in dettaglio analizzando le sfide con MCP di Shopify.)

Lo spettro che abbiamo attraversato in Quickchat AI Agents riflette un punto più ampio. Il giusto livello di controllo dipende dal tuo caso d’uso. Remote MCP funziona bene per la prototipazione rapida. Le AI Actions individuali ti danno controllo granulare per agent in produzione rivolti ai clienti. Generate from Text consente all’AI di ricercare l’API e costruire per te la definizione dello strumento quando sei ancora in fase di esplorazione.

E a ogni livello il pattern sottostante è lo stesso. Un LLM, un insieme di strumenti, un loop. Che gli strumenti siano comandi bash, endpoint API, server MCP o attuatori robotici, sono strumenti fino in fondo.