Come Costruire il Tuo Primo Agente IA in 15 Minuti

Indice dei contenuti

Aggiornato giugno 2026.

TL;DR: Non ti serve un framework, un corso o un dottorato. Ti servono Node.js, l’SDK di Anthropic e 25 righe di TypeScript. Questo tutorial costruisce un agente reale e funzionante — un riassuntore di contenuti strutturato che puoi distribuire su Cloudflare nella stessa sessione. L’unico prerequisito è una chiave API gratuita.

[Lettura dell’operatore] La cosa più comune che sento dai fondatori che vogliono automatizzare con l’IA è “prima devo imparare di più”. Non è vero. Il pattern dell’agente è semplice, e il modo più veloce per capirlo è costruirne uno. Ecco il percorso esatto che seguirei se ripartissi da zero oggi.

Perché la maggior parte dei tutorial “costruisci un agente IA” ti delude

O usano Python (ottimo per gli ingegneri ML, attrito per tutti gli altri), nascondono il codice reale dietro un framework come LangChain, o costruiscono qualcosa di troppo astratto per collegarlo al tuo lavoro reale.

Questo tutorial fa tre cose in modo diverso:

1. Solo TypeScript — se hai mai scritto JavaScript, puoi seguire questo
2. Nessun framework — vedrai ogni riga di codice che tocca il modello
3. Un output utile — costruirai un riassuntore strutturato che puoi davvero usare su email dei clienti, recensioni o note di riunioni

Cosa stai costruendo

Un agente riassuntore di contenuti: incolla qualsiasi blocco di testo e ricevi indietro un riassunto strutturato in un formato coerente. Una richiesta HTTP in entrata, un riassunto pulito in uscita.

Perché questo come primo progetto: il pattern — prompt di sistema + input dell’utente → output strutturato — è il fondamento di ogni agente che gestisco. Cambia il prompt di sistema e ottieni un risponditore di domande, un riscrittore di tono, un classificatore o un generatore di bozze. Impara questo una volta e avrai imparato l’80% di ciò che gli agenti in produzione fanno davvero.

Prerequisiti (2 minuti)

• Node.js 18+ — verifica con node --version. Installa da nodejs.org se necessario.
• Una chiave API di Anthropic — registrati su Claude, prendi una chiave dalla console. Il piano gratuito funziona.
• Un terminale e un editor di testo.

Niente Docker. Niente ambiente virtuale. Niente pip install di nulla.

Passo 1: Creare il progetto (2 minuti)

mkdir my-first-agent && cd my-first-agent
npm init -y
npm install @anthropic-ai/sdk
npm install -D tsx typescript

Aggiungi uno script a package.json così da poter eseguire l’agente facilmente:

{
  "scripts": {
    "agent": "tsx agent.ts"
  }
}

Passo 2: Scrivere l’agente (5 minuti)

Crea agent.ts e incolla questo:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const SYSTEM_PROMPT = `You are a precise content summarizer. When given any block of text, return a structured summary in this exact format:

**One-line summary:** <the core point in one sentence>

**Key points:**
- <point 1>
- <point 2>
- <point 3 if applicable>

**Action item (if any):** <one concrete next step, or "None">

Be specific. No filler. Under 150 words total.`;

async function summarize(text: string): Promise<string> {
  const message = await client.messages.create({
    model: "claude-haiku-4-5",
    max_tokens: 512,
    system: SYSTEM_PROMPT,
    messages: [{ role: "user", content: text }],
  });

  const block = message.content[0];
  if (block.type !== "text") throw new Error("Unexpected response type");
  return block.text;
}

const sample = `
  Hey team — following up on the Q2 review meeting.
  We agreed to push the launch to July 15th instead of June 30th
  due to the payment integration delay. Marketing needs the new
  landing page copy by June 20th or we can't start the email campaign.
  Budget for the launch campaign is confirmed at $8,000.
  Please confirm receipt.
`;

const result = await summarize(sample);
console.log(result);

Passo 3: Eseguirlo (1 minuto)

ANTHROPIC_API_KEY=sk-ant-... npm run agent

Output atteso:

**One-line summary:** Launch pushed to July 15th due to payment delay; landing page copy needed by June 20th to unblock email campaign.

**Key points:**
- Launch date moved from June 30th to July 15th
- Landing page copy deadline: June 20th (blocks email campaign)
- Campaign budget confirmed at $8,000

**Action item (if any):** Confirm receipt and deliver landing page copy by June 20th.

Questo è un agente IA funzionante. Input reale, prompt di sistema personalizzato, output strutturato. Il tutto è di 30 righe di codice.

Passo 4: Personalizzalo per il tuo caso d’uso

Il prompt di sistema è l’unica cosa che rende questo agente tuo. Ecco tre alternative pronte all’uso:

Classificatore di recensioni dei clienti:

Classify this customer review as POSITIVE, NEGATIVE, or MIXED.
Then extract the main complaint or praise in one sentence.
Format: SENTIMENT: <label>
RESUME: <one sentence>

Trascrizione di riunione → attività da svolgere:

Extract all action items from this meeting transcript.
Format each as: [OWNER if mentioned] [ACTION] by [DEADLINE if mentioned]
If owner or deadline is not stated, leave those fields blank.
Return a numbered list. No preamble.

Riscrittore di tono per i social:

Rewrite this text in a direct, confident, first-person tone for LinkedIn.
Remove hedging language ("I think", "maybe", "sort of").
Keep it under 200 words. Return only the rewritten text, no commentary.

Ognuno di questi è lo stesso agente di 30 righe con un prompt di sistema diverso. Non ti serve un nuovo progetto per ciascuno — basta aggiornare SYSTEM_PROMPT ed eseguire di nuovo.

Passo 5: Distribuire in produzione

Uno script locale è un prototipo. Un agente in produzione gira secondo una pianificazione o in risposta a eventi. Il percorso che uso: Cloudflare Workers.

I Workers sono gratuiti fino a 100k richieste/giorno, si distribuiscono in pochi secondi e ti danno trigger cron, storage KV e code senza dover gestire alcuna infrastruttura.

Installa Wrangler e genera l’impalcatura di un Worker:

npm install -g wrangler
wrangler init my-agent-worker --template worker-typescript
cd my-agent-worker
npm install @anthropic-ai/sdk

Memorizza la tua chiave API come secret (mai nel codice):

wrangler secret put ANTHROPIC_API_KEY

Sostituisci src/index.ts con:

import Anthropic from "@anthropic-ai/sdk";

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const { text } = await request.json<{ text: string }>();

    const client = new Anthropic({ apiKey: env.ANTHROPIC_API_KEY });
    const message = await client.messages.create({
      model: "claude-haiku-4-5",
      max_tokens: 512,
      system: YOUR_SYSTEM_PROMPT,
      messages: [{ role: "user", content: text }],
    });

    const block = message.content[0];
    if (block.type !== "text") return Response.json({ error: "Bad response" }, { status: 500 });
    return Response.json({ summary: block.text });
  },
};

Distribuisci:

wrangler deploy

Ora hai un endpoint API live all’indirizzo https://my-agent-worker.<your-subdomain>.workers.dev. Chiamalo da Zapier, da uno script di Google Sheets, da un’app mobile — da qualsiasi posto che possa effettuare una richiesta HTTP.

Cosa costruire dopo

Una volta che hai il pattern di base funzionante, la complessità arriva in tre varianti:

Uso degli strumenti (tool use) — lascia che sia il modello a decidere quando chiamare le API esterne. Invece di eseguire sempre la stessa logica, il modello sceglie quale strumento invocare in base all’input. È così che costruisci agenti che cercano, scrivono su database o inviano notifiche.

Concatenamento (chaining) — passa l’output di un agente come input di un altro. Un classificatore instrada verso un risponditore; un riassuntore alimenta un traduttore. La maggior parte degli agenti che gestisco in produzione sono catene di due o tre passaggi, non singole chiamate.

Trigger cron — aggiungi [triggers] crons = ["0 8 * * *"] a wrangler.toml e il tuo agente gira secondo una pianificazione. Niente polling, niente server sempre acceso. È così che funziona la pipeline di contenuti che uso per gestire questo sito.

Ho trattato tutti e tre i pattern con codice TypeScript completo in Lo stack di agenti che uso per gestire oltre 30 agenti in produzione — quel post riprende da dove finisce questo.

La conclusione dell’operatore

Il divario tra “pensare di costruire un agente” e “avere un agente distribuito” è di circa 15 minuti e 30 righe di codice. Il prompt di sistema è il prodotto — investi la tua energia lì, non nella scelta di un framework. Se l’agente ti fa risparmiare un’ora a settimana, sono 50 ore l’anno. Costruisci prima la versione semplice, vedi se si ripaga, poi aggiungi complessità solo quando il caso d’uso lo richiede.