Creare agenti IA con il Claude Agent SDK: una guida pratica

Il Claude Agent SDK ti offre accesso programmatico allo stesso agent loop che alimenta Claude Code. I tuoi agenti possono leggere file, eseguire comandi shell, cercare sul web, modificare codice, chiamare API esterne tramite server MCP e orchestrare sub-agenti - il tutto con poche righe di TypeScript o Python.

A differenza del Client SDK standard di Anthropic, dove devi costruire il tuo tool loop, l'Agent SDK gestisce internamente l'esecuzione dei tool, la gestione del contesto, i retry e l'orchestrazione. Tu descrivi cosa vuoi, fornisci gli strumenti, e l'agente si occupa del resto.

Architettura

L'SDK segue un loop semplice: raccogliere il contesto, agire, verificare, ripetere.

Il punto di ingresso principale e query(), che restituisce un iteratore asincrono che trasmette messaggi in streaming mentre l'agente lavora. Ogni messaggio ti dice cosa sta facendo l'agente: ragionamento, chiamata a un tool, ricezione di un risultato o consegna dell'output finale.

Per iniziare

Installazione

# TypeScript
npm install @anthropic-ai/claude-agent-sdk

# Python
pip install claude-agent-sdk

Hai bisogno di una chiave API Anthropic impostata come ANTHROPIC_API_KEY nel tuo ambiente.

Il tuo primo agente

import { query } from "@anthropic-ai/claude-agent-sdk";

const conversation = query({
  prompt: "Find all TODO comments in the codebase and create a summary",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
  },
});

for await (const message of conversation) {
  if (message.type === "assistant") {
    process.stdout.write(message.content);
  }
  if (message.type === "result" && message.subtype === "success") {
    console.log("\nDone:", message.result);
  }
}

Tutto qui. L'agente usera Glob per trovare i file, Grep per cercare i pattern TODO, Read per ispezionare le corrispondenze e restituire un riassunto strutturato. Non devi scrivere la logica di orchestrazione - l'SDK se ne occupa.

Equivalente Python

from claude_agent_sdk import query

async for message in query(
    prompt="Find all TODO comments in the codebase and create a summary",
    options={"allowed_tools": ["Read", "Glob", "Grep"]},
):
    if message.type == "assistant":
        print(message.content, end="")
    if message.type == "result" and message.subtype == "success":
        print(f"\nDone: {message.result}")

Tool integrati

L'SDK include gli stessi tool disponibili in Claude Code:

Puoi controllare quali tool l'agente puo utilizzare tramite allowedTools. Se un tool non e nella lista, l'agente non puo chiamarlo.

Modalita di permesso

Dato che gli agenti eseguono comandi reali su sistemi reali, i permessi sono importanti.

const conversation = query({
  prompt: "Refactor the auth module to use JWT",
  options: {
    allowedTools: ["Read", "Edit", "Glob", "Grep", "Bash"],
    permissionMode: "acceptEdits",
  },
});

Per l'uso in produzione, esegui sempre gli agenti in ambienti sandbox (container, VM) e usa la modalita di permesso piu restrittiva che consenta comunque all'agente di svolgere il proprio lavoro.

Creare tool personalizzati con MCP

La vera potenza dell'SDK sta nell'estendere gli agenti con i tuoi strumenti. I tool personalizzati vengono definiti come server MCP in-process - nessuna gestione di sottoprocessi, nessun overhead di rete.

Esempio: tool meteo

import { tool, createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const getTemperature = tool(
  "get_temperature",
  "Get the current temperature at a location",
  {
    latitude: z.number().describe("Latitude"),
    longitude: z.number().describe("Longitude"),
  },
  async ({ latitude, longitude }) => {
    const res = await fetch(
      `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m&temperature_unit=celsius`
    );
    const data = await res.json();
    return {
      content: [
        {
          type: "text",
          text: `Current temperature: ${data.current.temperature_2m}C`,
        },
      ],
    };
  }
);

const weatherServer = createSdkMcpServer({
  name: "weather",
  version: "1.0.0",
  tools: [getTemperature],
});

for await (const message of query({
  prompt: "What's the weather like in Rome?",
  options: {
    mcpServers: { weather: weatherServer },
    allowedTools: ["mcp__weather__get_temperature"],
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

I tool personalizzati seguono la convenzione di naming mcp__{nome_server}__{nome_tool}. Puoi usare i caratteri jolly in allowedTools: "mcp__weather__*" abilita tutti i tool del server meteo.

Esempio: tool per query al database

const queryDb = tool(
  "query_database",
  "Run a read-only SQL query against the application database",
  {
    sql: z.string().describe("SQL SELECT query to execute"),
  },
  async ({ sql }) => {
    // Validate: only allow SELECT queries
    if (!sql.trim().toUpperCase().startsWith("SELECT")) {
      return {
        content: [{ type: "text", text: "Error: Only SELECT queries are allowed." }],
      };
    }

    const result = await pool.query(sql);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result.rows, null, 2),
        },
      ],
    };
  }
);

Connettere server MCP esterni

Oltre ai tool in-process, puoi connetterti a qualsiasi server MCP esistente - gli stessi server che funzionano con Claude Desktop, Cursor e altri client MCP.

for await (const message of query({
  prompt: "Check the latest issues in the frontend repo and summarize them",
  options: {
    mcpServers: {
      github: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN },
      },
    },
    allowedTools: ["mcp__github__*"],
  },
})) {
  // ...
}

Puoi combinare piu server MCP. L'agente vede tutti i tool di tutti i server connessi e li utilizza secondo necessita.

Orchestrazione multi-agente

Per workflow complessi, puoi definire sub-agenti specializzati a cui l'agente principale delega. Ogni sub-agente ha il proprio prompt, i propri tool e la propria area di competenza.

for await (const message of query({
  prompt: "Review the PR, check for security issues, and update the changelog",
  options: {
    allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep", "Agent"],
    agents: [
      {
        name: "security-reviewer",
        description: "Reviews code for security vulnerabilities",
        prompt: "You are a security expert. Analyze code for OWASP Top 10 vulnerabilities.",
        allowedTools: ["Read", "Glob", "Grep"],
      },
      {
        name: "changelog-writer",
        description: "Updates the CHANGELOG.md file based on recent changes",
        prompt: "You maintain the project changelog. Follow Keep a Changelog format.",
        allowedTools: ["Read", "Edit", "Bash"],
      },
    ],
  },
})) {
  // The parent agent will:
  // 1. Read the PR diff
  // 2. Delegate security review to security-reviewer
  // 3. Delegate changelog update to changelog-writer
  // 4. Synthesize results
}

Includi "Agent" in allowedTools del genitore per abilitare la delega. I sub-agenti vengono eseguiti con i propri tool e non possono accedere a quelli del genitore a meno che non sia esplicitamente concesso.

Sessioni e continuita

Gli agenti possono mantenere il contesto tra piu query usando le sessioni. Cattura il session_id dalla prima interazione e passalo in resume per le query successive.

let sessionId: string | undefined;

// First query
for await (const message of query({
  prompt: "Read the project structure and understand the architecture",
  options: { allowedTools: ["Read", "Glob", "Grep"] },
})) {
  if (message.type === "init") {
    sessionId = message.session_id;
  }
}

// Follow-up query (same session, full context preserved)
for await (const message of query({
  prompt: "Now refactor the auth module based on what you learned",
  resume: sessionId,
  options: { allowedTools: ["Read", "Edit", "Bash"] },
})) {
  // Agent remembers the full project context from the first query
}

Claude Managed Agents

Se non vuoi gestire tu stesso l'infrastruttura degli agenti, i Claude Managed Agents (lanciati ad aprile 2026) offrono un servizio cloud completamente gestito. Anthropic si occupa dei container, dello scaling e mette a disposizione una API in streaming.

La differenza fondamentale: con l'Agent SDK, esegui l'agent loop nella tua infrastruttura. Con i Managed Agents, Anthropic ospita e gestisce l'agente per te. Interagisci tramite un'API basata su sessioni e ricevi eventi tramite Server-Sent Events.

Prezzi:

• Agent SDK: solo le tariffe standard per token dell'API Claude. L'hosting e a tuo carico.
• Managed Agents: tariffe per token piu $0,08 per ora di sessione (fatturati al millisecondo).

Best practice per la produzione

1. Usa sempre un sandbox

Non eseguire mai agenti con permessi illimitati su una macchina di produzione. Usa container (Docker, Fly.io, Modal) o ambienti sandbox (E2B, Vercel Sandbox).

2. Limita l'accesso ai tool

Segui il principio del privilegio minimo. Un agente che genera report non ha bisogno di Bash o Write.

// Too permissive
allowedTools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]

// Better: only what's needed
allowedTools: ["Read", "Glob", "Grep"]

3. Usa gli hook come guardrail

Gli hook ti permettono di intercettare le chiamate ai tool prima e dopo l'esecuzione. Usali per logging, validazione e rate limiting.

const conversation = query({
  prompt: "Analyze the codebase",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
    hooks: {
      PreToolUse: async (toolName, input) => {
        console.log(`Tool call: ${toolName}`, input);
        // Return false to block the call
        if (toolName === "Bash" && input.command.includes("rm")) {
          return false;
        }
        return true;
      },
    },
  },
});

4. Gestisci gli errori in modo appropriato

L'agent loop puo produrre errori - fallimenti dei tool, limiti di rate dell'API, overflow della finestra di contesto. Controlla sempre i tipi di messaggio.

for await (const message of conversation) {
  switch (message.type) {
    case "assistant":
      // Agent reasoning
      break;
    case "tool_use":
      // Agent is calling a tool
      break;
    case "result":
      if (message.subtype === "error") {
        console.error("Agent failed:", message.error);
      }
      break;
  }
}

5. Monitora il consumo di token

Gli agent loop possono consumare una quantita significativa di token, specialmente con codebase di grandi dimensioni. L'SDK include la compattazione automatica del contesto, ma dovresti comunque monitorare l'utilizzo.

Conclusione

Il Claude Agent SDK trasforma un LLM da una macchina che risponde a domande in qualcosa di piu simile a uno sviluppatore junior. I tuoi agenti possono leggere, scrivere, eseguire, verificare e iterare - lo stesso workflow che segue un essere umano.

Parti in piccolo: crea un agente con pochi tool integrati. Poi aggiungi tool MCP personalizzati per il tuo dominio specifico. Scala verso l'orchestrazione multi-agente quando i tuoi workflow richiedono specializzazione.

L'agent loop e lo stesso che alimenta Claude Code. Se puo creare software, i tuoi agenti possono fare altrettanto.

Checklist per iniziare:

• Installa l'SDK (npm install @anthropic-ai/claude-agent-sdk)
• Imposta ANTHROPIC_API_KEY nel tuo ambiente
• Crea un agente semplice con i tool integrati (Read, Glob, Grep)
• Aggiungi un tool personalizzato tramite server MCP in-process
• Connetti un server MCP esterno (GitHub, PostgreSQL, ecc.)
• Implementa l'orchestrazione multi-agente con sub-agenti
• Configura un ambiente sandbox per la produzione
• Aggiungi hook per logging e guardrail