Creare un Agente AI con JavaScript e Claude: Tutorial Pratico
Cosa sono gli agenti AI e perché cambiano tutto
Un chatbot risponde a domande. Un agente AI prende decisioni, usa strumenti, e porta a termine obiettivi in modo autonomo. La differenza è sostanziale: un agente può cercare informazioni sul web, leggere file, scrivere codice, eseguirlo e iterare — tutto in autonomia, guidato da un obiettivo che tu gli dai.
Con l’API di Claude (Anthropic) e il meccanismo di tool use, puoi costruire agenti reali in JavaScript in poche ore. In questo tutorial costruiamo un agente completo, partendo dal setup fino al loop di esecuzione.
Setup: installazione Anthropic SDK
// Installa l'SDK
// npm install @anthropic-ai/sdk
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic({
apiKey: process.env.ANTHROPIC_API_KEY
});
// Test base: verifica che funzioni
const test = await client.messages.create({
model: 'claude-sonnet-4-6',
max_tokens: 100,
messages: [{ role: 'user', content: 'Rispondi solo: OK' }]
});
console.log(test.content[0].text); // OKTool Use: dare strumenti all’agente
Il tool use permette a Claude di “richiedere” l’esecuzione di funzioni esterne. Tu definisci i tool (nome, descrizione, schema input), Claude decide quando e come usarli, tu esegui il codice e restituisci il risultato. Ecco la struttura di un tool:
const tools = [
{
name: "get_weather",
description: "Ottieni le previsioni meteo per una città",
input_schema: {
type: "object",
properties: {
city: {
type: "string",
description: "Nome della città (es: 'Roma', 'Milano')"
},
days: {
type: "number",
description: "Numero di giorni di previsione (1-7)"
}
},
required: ["city"]
}
}
];Il loop dell’agente: run → tool_result → run
Il cuore di ogni agente AI è il loop di esecuzione. Claude risponde, eventualmente richiede un tool, tu esegui il tool e restituisci il risultato, e Claude continua. Ecco il pattern completo:
async function runAgent(task, tools, executeTool) {
const messages = [{ role: 'user', content: task }];
const MAX_ITERATIONS = 15; // sicurezza: evita loop infiniti
let iterations = 0;
while (iterations < MAX_ITERATIONS) {
iterations++;
const response = await client.messages.create({
model: 'claude-sonnet-4-6',
max_tokens: 4096,
tools,
messages
});
// Agente ha finito
if (response.stop_reason === 'end_turn') {
const text = response.content.find(b => b.type === 'text');
return text?.text ?? 'Completato';
}
// Agente vuole usare un tool
if (response.stop_reason === 'tool_use') {
messages.push({ role: 'assistant', content: response.content });
const toolResults = [];
for (const block of response.content) {
if (block.type === 'tool_use') {
console.log(`🔧 Tool: ${block.name}`, block.input);
const result = await executeTool(block.name, block.input);
toolResults.push({
type: 'tool_result',
tool_use_id: block.id,
content: JSON.stringify(result)
});
}
}
messages.push({ role: 'user', content: toolResults });
}
}
return 'Max iterazioni raggiunto';
}
// Utilizzo
const result = await runAgent(
'Cerca le previsioni meteo per Roma per i prossimi 3 giorni e scrivimi un riassunto',
tools,
async (name, input) => {
if (name === 'get_weather') {
// qui chiami la vera API meteo
return { city: input.city, forecast: '...' };
}
}
);
console.log(result);Casi d’uso reali per developer
Ecco tre agenti pratici che puoi costruire oggi:
- Code Review Agent: riceve un diff Git, analizza il codice, suggerisce miglioramenti — automaticamente su ogni PR
- Doc Generator Agent: legge i file sorgente JS/TS, genera JSDoc per ogni funzione, aggiorna automaticamente la documentazione
- Email Responder Agent: legge le email in arrivo, classifica per priorità, genera bozze di risposta contestuali
Per la parte di integrazione API, ti consiglio di leggere anche il nostro articolo su Claude API: Come Automatizzare il Workflow da Developer. Per l’automazione senza codice, vedi n8n + Claude per automatizzare il business.
FAQ e Domande Frequenti
Qual è la differenza tra tool_use e function calling?
Sono la stessa cosa con nomi diversi: OpenAI chiama “function calling” quello che Anthropic chiama “tool use”. Entrambi permettono all’LLM di richiedere l’esecuzione di codice esterno per ottenere informazioni o compiere azioni nel mondo reale.
Come gestisco errori nell’esecuzione dei tool?
Quando un tool fallisce, restituisci un tool_result con is_error: true e un messaggio descrittivo. Claude capirà l’errore e potrà decidere di riprovare, usare un approccio alternativo, o comunicare il problema all’utente.
Posso usare più tool in parallelo?
Sì. Con tool_choice: "auto" Claude può richiedere più tool contemporaneamente (parallel tool use). Gestisci l’array di tool_use nel response.content e fornisci tutti i tool_result prima di fare la chiamata successiva.
Quanto costa usare Claude API per un agente?
Claude claude-sonnet-4-6 costa ~$3/1M token input e $15/1M output. Un agente che gira 100 task/giorno con ~5.000 token/task costa circa $7-15/mese. Monitora sempre il numero di iterazioni del loop con un limite massimo.
Quali modelli Claude sono migliori per gli agenti AI?
Claude Sonnet 4.6 è il punto di equilibrio ottimale: capacità avanzate a costo contenuto. Per task semplici usa Haiku (costo molto basso). Per ragionamento complesso multi-step usa Opus 4.6. Tutti supportano il tool use.
Conclusione
Costruire un agente AI con Claude e JavaScript è sorprendentemente accessibile. Il pattern è sempre lo stesso: definisci i tool, scrivi il loop, gestisci i risultati. La complessità reale sta nella qualità della descrizione dei tool — più sono precisi, meglio Claude li usa.
Inizia con un singolo tool su un problema reale che hai. In un weekend puoi avere il tuo primo agente in produzione.
💡 Pro tip: Inizia sempre con un singolo tool ben definito prima di costruire agenti complessi. Un agente che fa bene una cosa vale più di uno che fa male dieci cose.
🔧 Strumenti: @anthropic-ai/sdk, Zod (validazione schema), LangChain.js (orchestrazione avanzata)
🎯 Nota: Implementa sempre un limite di iterazioni (MAX_ITERATIONS) per evitare loop infiniti e costi non controllati in produzione.
