Un agente utile non si limita a chattare: legge una documentazione, seleziona uno strumento, chiama un’API e usa il risultato nel passaggio successivo. In questa guida il caso concreto è WordPress, ma il metodo vale per qualsiasi servizio con API documentate.
Dalla documentazione API a un agente operativo
Il flusso è composto da quattro livelli: fonte della documentazione, definizione degli strumenti, orchestrazione dell’agente e verifica del risultato. Saltare uno di questi livelli produce demo impressionanti ma difficili da controllare.
- Raccogli endpoint, parametri, autenticazione ed errori documentati.
- Crea uno strumento per ogni operazione, con input espliciti.
- Distingui sempre operazioni di lettura da creazione, modifica o cancellazione.
- Registra richiesta, risposta ed esito verificato senza salvare segreti nei log.
Perché usare Markdown invece di un PDF
Markdown tende a conservare testo, titoli, endpoint e parametri senza appesantire il contesto con impaginazione. La conversione non è però una garanzia: controlla tabelle, esempi e intestazioni, perché materiale incompleto porta a schemi e chiamate API sbagliati.
Ti sta piacendo?
Ricevi una guida pratica ogni settimana. AI, tool e automazioni.
Il caso WordPress: lettura prima della modifica
Con WordPress REST API partirei da una chiamata GET limitata a pochi campi. Solo dopo aver verificato URL, autenticazione e formato della risposta aggiungerei azioni di scrittura. Le credenziali devono restare fuori dal prompt e dal repository.
GET /wp-json/wp/v2/posts?per_page=5&_fields=id,slug,title,modifiedUna risposta HTTP positiva non dimostra che il task sia riuscito: l’agente deve leggere di nuovo la risorsa esatta e confrontare lo stato atteso con quello reale. Per le operazioni distruttive servono approvazione esplicita e un piano di rollback.
Come progettare strumenti che il modello capisce
Nomi e descrizioni devono essere concreti. list_posts, get_post e update_post sono più controllabili di un generico wordpress. Ogni schema deve limitare i campi ammessi e spiegare gli errori che l’agente può correggere.
Come orchestrare gli strumenti
L’utente formula l’obiettivo, il modello sceglie l’operazione, il connettore traduce la richiesta per l’API e il risultato torna all’agente. Un connettore mal progettato rende inaffidabile anche un modello valido: orchestrazione e schemi sono parte del prodotto, non dettagli della demo.
Un percorso di test ripetibile
- Esegui una lettura nota e confronta ID e slug.
- Prova input mancanti o non validi e verifica che lo strumento fallisca in modo leggibile.
- Simula una scrittura in un ambiente di test o in bozza.
- Dopo la scrittura, rileggi l’oggetto e verifica i campi esatti.
Quale ruolo ha il modello locale
Il modello decide quando usare gli strumenti e come interpretare i risultati. Puoi collegare Claude Code a Ollama, ma il fatto che il modello sia locale non rende locali le API chiamate: se l’agente interroga WordPress o un servizio cloud, quei dati attraversano comunque la rete verso il servizio scelto.
Per un altro esempio sul percorso completo dei dati, vedi OpenUI in locale con Ollama. Per i rischi di scambiare una prima analisi per una validazione completa, leggi anche sicurezza del vibe coding con agenti AI di pentest.
Per installare Claude Code con Ollama, variabili ambiente, contesto e troubleshooting, usa la guida principale a Claude Code con Ollama. Separare i due intenti evita di far competere questa pagina metodologica con il tutorial di configurazione.
Checklist prima di usare l’agente su dati reali
- Permessi minimi e credenziali separate per ambiente.
- Allowlist degli endpoint e dei campi modificabili.
- Conferma umana per scritture e cancellazioni.
- Log privi di token e dati sensibili.
- Readback obbligatorio dopo ogni mutazione.
- Backup o versione precedente disponibili prima del test.
Come valutare il risultato oltre l’effetto wow
Verifica che recuperi i dati corretti, distingua lettura e modifica, segnali risposte incomplete, non inventi dati mancanti, mantenga il contesto e chieda conferma prima di azioni delicate. Una risposta plausibile basata su dati sbagliati non supera il test.
Limiti pratici da considerare
Documentazione incompleta, conversioni che perdono esempi, parametri gestiti male e autorizzazioni troppo ampie sono limiti concreti. Una demo funzionante non è un prodotto pronto: restano test, error handling, permessi, privacy e verifica umana.
Domande frequenti e fonti
Serve Ollama per costruire un agente con API?
La WordPress REST API può modificare contenuti?
Un modello locale evita ogni traffico di rete?
Come riduco il rischio di modifiche sbagliate?
Aggiungi francescogruner.it come fonte preferita
Se leggi spesso i miei articoli su AI, automazione e tecnologia, ora puoi dire a Google che vuoi vedere più spesso i contenuti di francescogruner.it tra le notizie.
