TypeScript

Prerequisiti

Node.js 18+

Installazione

Installa @anthropic-ai/claude-code da NPM:

npm install -g @anthropic-ai/claude-code

Per visualizzare il codice sorgente dell’SDK TypeScript, visita la pagina @anthropic-ai/claude-code su NPM.

Utilizzo di base

L’interfaccia principale tramite l’SDK TypeScript è la funzione query, che restituisce un iteratore asincrono che trasmette i messaggi man mano che arrivano:

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

for await (const message of query({
  prompt: "Analizza le prestazioni del sistema",
  abortController: new AbortController(),
  options: {
    maxTurns: 5,
    systemPrompt: "Sei un ingegnere delle prestazioni",
    allowedTools: ["Bash", "Read", "WebSearch"]
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

Opzioni di configurazione

Argomento	Tipo	Descrizione	Predefinito
`abortController`	`AbortController`	Controller di interruzione per annullare le operazioni	`new AbortController()`
`additionalDirectories`	`string[]`	Directory aggiuntive da includere nella sessione	`undefined`
`allowedTools`	`string[]`	Elenco di strumenti che Claude è autorizzato a utilizzare	Tutti gli strumenti abilitati per impostazione predefinita
`appendSystemPrompt`	`string`	Testo da aggiungere al prompt di sistema predefinito	`undefined`
`canUseTool`	`CanUseTool`	Funzione di autorizzazione personalizzata per l’uso degli strumenti	`undefined`
`continue`	`boolean`	Continua la sessione più recente	`false`
`customSystemPrompt`	`string`	Sostituisce completamente il prompt di sistema predefinito	`undefined`
`cwd`	`string`	Directory di lavoro corrente	`process.cwd()`
`disallowedTools`	`string[]`	Elenco di strumenti che Claude non è autorizzato a utilizzare	`undefined`
`env`	`Dict<string>`	Variabili d’ambiente da impostare	`undefined`
`executable`	`'bun' \| 'deno' \| 'node'`	Quale runtime JavaScript utilizzare	`node` quando si esegue con Node.js, `bun` quando si esegue con Bun
`executableArgs`	`string[]`	Argomenti da passare all’eseguibile	`[]`
`fallbackModel`	`string`	Modello da utilizzare se il modello primario fallisce	`undefined`
`maxThinkingTokens`	`number`	Token massimi per il processo di ragionamento di Claude	`undefined`
`maxTurns`	`number`	Numero massimo di turni di conversazione	`undefined`
`mcpServers`	`Record<string, McpServerConfig>`	Configurazioni del server MCP	`undefined`
`model`	`string`	Modello Claude da utilizzare	Utilizza il predefinito dalla configurazione CLI
`pathToClaudeCodeExecutable`	`string`	Percorso dell’eseguibile Claude Code	Eseguibile fornito con `@anthropic-ai/claude-code`
`permissionMode`	`PermissionMode`	Modalità di autorizzazione per la sessione	`"default"` (opzioni: `"default"`, `"acceptEdits"`, `"bypassPermissions"`, `"plan"`)
`permissionPromptToolName`	`string`	Nome dello strumento MCP per i prompt di autorizzazione	`undefined`
`resume`	`string`	ID sessione da riprendere	`undefined`
`stderr`	`(data: string) => void`	Callback per l’output stderr	`undefined`
`strictMcpConfig`	`boolean`	Applica la validazione rigorosa della configurazione MCP	`undefined`

Conversazioni multi-turno

Per le conversazioni multi-turno, hai due opzioni.

Puoi generare risposte e riprenderle, oppure puoi utilizzare la modalità di input streaming che accetta un async/generator per un array di messaggi. Per ora, la modalità di input streaming è l’unico modo per allegare immagini tramite messaggi.

Riprendi con gestione della sessione

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

// Continua la conversazione più recente
for await (const message of query({
  prompt: "Ora refactorizza questo per migliori prestazioni",
  options: { continue: true }
})) {
  if (message.type === "result") console.log(message.result);
}

// Riprendi sessione specifica
for await (const message of query({
  prompt: "Aggiorna i test",
  options: {
    resume: "550e8400-e29b-41d4-a716-446655440000",
    maxTurns: 3
  }
})) {
  if (message.type === "result") console.log(message.result);
}

Modalità di input streaming

La modalità di input streaming ti permette di fornire messaggi come un iterabile asincrono invece di una singola stringa. Questo abilita conversazioni multi-turno, allegati di immagini e generazione dinamica di messaggi:

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

// Crea un generatore asincrono per i messaggi streaming
async function* generateMessages() {
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Inizia ad analizzare questa base di codice"
    }
  };
  
  // Aspetta qualche condizione o input dell'utente
  await new Promise(resolve => setTimeout(resolve, 1000));
  
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Ora concentrati sul modulo di autenticazione"
    }
  };
}

// Utilizza input streaming
for await (const message of query({
  prompt: generateMessages(),
  options: {
    maxTurns: 5,
    allowedTools: ["Read", "Grep", "Bash"]
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

Input streaming con immagini

La modalità di input streaming è l’unico modo per allegare immagini tramite messaggi:

import { query } from "@anthropic-ai/claude-code";
import { readFileSync } from "fs";

async function* messagesWithImage() {
  // Invia un'immagine con testo
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: [
        {
          type: "text",
          text: "Analizza questo screenshot e suggerisci miglioramenti"
        },
        {
          type: "image",
          source: {
            type: "base64",
            media_type: "image/png",
            data: readFileSync("screenshot.png", "base64")
          }
        }
      ]
    }
  };
}

for await (const message of query({
  prompt: messagesWithImage()
})) {
  if (message.type === "result") console.log(message.result);
}

Prompt di sistema personalizzati

I prompt di sistema definiscono il ruolo, l’expertise e il comportamento del tuo agente:

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

// Agente di risposta agli incidenti SRE
for await (const message of query({
  prompt: "L'API è down, investiga",
  options: {
    systemPrompt: "Sei un esperto SRE. Diagnostica i problemi sistematicamente e fornisci soluzioni attuabili.",
    maxTurns: 3
  }
})) {
  if (message.type === "result") console.log(message.result);
}

// Aggiungi al prompt di sistema predefinito
for await (const message of query({
  prompt: "Refactorizza questa funzione",
  options: {
    appendSystemPrompt: "Includi sempre gestione completa degli errori e test unitari.",
    maxTurns: 2
  }
})) {
  if (message.type === "result") console.log(message.result);
}

Strumenti personalizzati tramite MCP

Il Model Context Protocol (MCP) ti permette di dare ai tuoi agenti strumenti e capacità personalizzati:

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

// Agente SRE con strumenti di monitoraggio
for await (const message of query({
  prompt: "Investiga l'interruzione del servizio di pagamento",
  options: {
    mcpConfig: "sre-tools.json",
    allowedTools: ["mcp__datadog", "mcp__pagerduty", "mcp__kubernetes"],
    systemPrompt: "Sei un SRE. Usa i dati di monitoraggio per diagnosticare i problemi.",
    maxTurns: 4
  }
})) {
  if (message.type === "result") console.log(message.result);
}

Strumenti personalizzati utilizzando MCP

Puoi implementare strumenti personalizzati utilizzando MCP, ad esempio ecco come puoi creare uno strumento personalizzato per la gestione delle autorizzazioni.

const server = new McpServer({
  name: "Test permission prompt MCP Server",
  version: "0.0.1",
});

server.tool(
  "approval_prompt",
  'Simula un controllo di autorizzazione - approva se l\'input contiene "allow", altrimenti nega',
  {
    tool_name: z.string().describe("Il nome dello strumento che richiede l'autorizzazione"),
    input: z.object({}).passthrough().describe("L'input per lo strumento"),
    tool_use_id: z.string().optional().describe("L'ID univoco della richiesta di utilizzo dello strumento"),
  },
  async ({ tool_name, input }) => {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            JSON.stringify(input).includes("allow")
              ? {
                  behavior: "allow",
                  updatedInput: input,
                }
              : {
                  behavior: "deny",
                  message: "Autorizzazione negata dallo strumento test approval_prompt",
                }
          ),
        },
      ],
    };
  }
);

// Utilizza nell'SDK
import { query } from "@anthropic-ai/claude-code";

for await (const message of query({
  prompt: "Analizza la base di codice",
  options: {
    permissionPromptTool: "mcp__test-server__approval_prompt",
    mcpConfig: "my-config.json",
    allowedTools: ["Read", "Grep"]
  }
})) {
  if (message.type === "result") console.log(message.result);
}

Formati di output

Output di testo (predefinito)

// Output di testo predefinito
for await (const message of query({
  prompt: "Spiega il file src/components/Header.tsx"
})) {
  if (message.type === "result") {
    console.log(message.result);
    // Output: Questo è un componente React che mostra...
  }
}

Output JSON

// Raccogli tutti i messaggi per l'accesso simile a JSON
const messages = [];
for await (const message of query({
  prompt: "Come funziona il livello dati?"
})) {
  messages.push(message);
}

// Accedi al messaggio risultato con metadati
const result = messages.find(m => m.type === "result");
console.log({
  result: result.result,
  cost: result.total_cost_usd,
  duration: result.duration_ms
});

Formati di input

// Prompt diretto
for await (const message of query({
  prompt: "Spiega questo codice"
})) {
  if (message.type === "result") console.log(message.result);
}

// Da variabile
const userInput = "Spiega questo codice";
for await (const message of query({ prompt: userInput })) {
  if (message.type === "result") console.log(message.result);
}

Esempi di integrazione agenti

Agente di risposta agli incidenti SRE

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

// Agente automatizzato di risposta agli incidenti
async function investigateIncident(
  incidentDescription: string,
  severity = "medium"
) {
  const messages = [];

  for await (const message of query({
    prompt: `Incidente: ${incidentDescription} (Gravità: ${severity})`,
    options: {
      systemPrompt: "Sei un esperto SRE. Diagnostica il problema, valuta l'impatto e fornisci elementi d'azione immediati.",
      maxTurns: 6,
      allowedTools: ["Bash", "Read", "WebSearch", "mcp__datadog"],
      mcpConfig: "monitoring-tools.json"
    }
  })) {
    messages.push(message);
  }

  return messages.find(m => m.type === "result");
}

// Utilizzo
const result = await investigateIncident("API di pagamento che restituisce errori 500", "high");
console.log(result.result);

Revisione di sicurezza automatizzata

import { query } from "@anthropic-ai/claude-code";
import { execSync } from "child_process";

async function auditPR(prNumber: number) {
  // Ottieni diff PR
  const prDiff = execSync(`gh pr diff ${prNumber}`, { encoding: 'utf8' });

  const messages = [];
  for await (const message of query({
    prompt: prDiff,
    options: {
      systemPrompt: "Sei un ingegnere della sicurezza. Rivedi questa PR per vulnerabilità, pattern insicuri e problemi di conformità.",
      maxTurns: 3,
      allowedTools: ["Read", "Grep", "WebSearch"]
    }
  })) {
    messages.push(message);
  }

  return messages.find(m => m.type === "result");
}

// Utilizzo
const report = await auditPR(123);
console.log(JSON.stringify(report, null, 2));

Assistente legale multi-turno

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

async function legalReview() {
  // Inizia sessione di revisione legale
  let sessionId: string;

  for await (const message of query({
    prompt: "Inizia sessione di revisione legale",
    options: { maxTurns: 1 }
  })) {
    if (message.type === "system" && message.subtype === "init") {
      sessionId = message.session_id;
    }
  }

  // Revisione multi-step utilizzando la stessa sessione
  const steps = [
    "Rivedi contract.pdf per clausole di responsabilità",
    "Controlla conformità ai requisiti GDPR",
    "Genera riassunto esecutivo dei rischi"
  ];

  for (const step of steps) {
    for await (const message of query({
      prompt: step,
      options: { resume: sessionId, maxTurns: 2 }
    })) {
      if (message.type === "result") {
        console.log(`Passo: ${step}`);
        console.log(message.result);
      }
    }
  }
}

Schema dei messaggi

I messaggi restituiti dall’API JSON sono rigorosamente tipizzati secondo il seguente schema:

type SDKMessage =
  // Un messaggio dell'assistente
  | {
      type: "assistant";
      uuid: string;
      session_id: string;
      message: Message; // dall'SDK Anthropic
      parent_tool_use_id: string | null;
    }

  // Un messaggio utente (input)
  | {
      type: "user";
      uuid?: string;
      session_id: string;
      message: MessageParam; // dall'SDK Anthropic
      parent_tool_use_id: string | null;
    }

  // Un messaggio utente (output/replay con UUID richiesto)
  | {
      type: "user";
      uuid: string;
      session_id: string;
      message: MessageParam; // dall'SDK Anthropic
      parent_tool_use_id: string | null;
    }

  // Emesso come ultimo messaggio in caso di successo
  | {
      type: "result";
      subtype: "success";
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      num_turns: number;
      result: string;
      total_cost_usd: number;
      usage: Usage;
      permission_denials: SDKPermissionDenial[];
    }

  // Emesso come ultimo messaggio in caso di errore o turni massimi
  | {
      type: "result";
      subtype: "error_max_turns" | "error_during_execution";
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      num_turns: number;
      total_cost_usd: number;
      usage: Usage;
      permission_denials: SDKPermissionDenial[];
    }

  // Emesso come primo messaggio all'inizio di una conversazione
  | {
      type: "system";
      subtype: "init";
      uuid: UUID;
      session_id: string;
      apiKeySource: "user" | "project" | "org" | "temporary";
      cwd: string;
      tools: string[];
      mcp_servers: {
        name: string;
        status: string;
      }[];
      model: string;
      permissionMode: "default" | "acceptEdits" | "bypassPermissions" | "plan";
      slash_commands: string[];
      output_style: string;
    };

  type SDKPermissionDenial = {
    tool_name: string;
    tool_use_id: string;
    tool_input: Record<string, unknown>;
  }

Tipi di supporto aggiuntivi:

I tipi Message, MessageParam e Usage sono disponibili nell’SDK TypeScript di Anthropic.

Risorse correlate

Utilizzo CLI e controlli - Documentazione CLI completa
Integrazione GitHub Actions - Automatizza il tuo flusso di lavoro GitHub con Claude
Flussi di lavoro comuni - Guide passo-passo per casi d’uso comuni

Iniziare

Sviluppa con Claude Code

Claude Code SDK

Distribuzione

Amministrazione

Configurazione

Riferimento

Risorse

Prerequisiti

Installazione

Utilizzo di base

Opzioni di configurazione

Conversazioni multi-turno

Riprendi con gestione della sessione

Modalità di input streaming

Input streaming con immagini

Prompt di sistema personalizzati

Strumenti personalizzati tramite MCP

Strumenti personalizzati utilizzando MCP

Formati di output

Output di testo (predefinito)

Output JSON

Formati di input

Esempi di integrazione agenti

Agente di risposta agli incidenti SRE

Revisione di sicurezza automatizzata

Assistente legale multi-turno

Schema dei messaggi

Risorse correlate

Iniziare

Sviluppa con Claude Code

Claude Code SDK

Distribuzione

Amministrazione

Configurazione

Riferimento

Risorse

​Prerequisiti

​Installazione

​Utilizzo di base

​Opzioni di configurazione

​Conversazioni multi-turno

​Riprendi con gestione della sessione

​Modalità di input streaming

​Input streaming con immagini

​Prompt di sistema personalizzati

​Strumenti personalizzati tramite MCP

​Strumenti personalizzati utilizzando MCP

​Formati di output

​Output di testo (predefinito)

​Output JSON

​Formati di input

​Esempi di integrazione agenti

​Agente di risposta agli incidenti SRE

​Revisione di sicurezza automatizzata

​Assistente legale multi-turno

​Schema dei messaggi

​Risorse correlate

Prerequisiti

Installazione

Utilizzo di base

Opzioni di configurazione

Conversazioni multi-turno

Riprendi con gestione della sessione

Modalità di input streaming

Input streaming con immagini

Prompt di sistema personalizzati

Strumenti personalizzati tramite MCP

Strumenti personalizzati utilizzando MCP

Formati di output

Output di testo (predefinito)

Output JSON

Formati di input

Esempi di integrazione agenti

Agente di risposta agli incidenti SRE

Revisione di sicurezza automatizzata

Assistente legale multi-turno

Schema dei messaggi

Risorse correlate