SDK TypeScript

Questa libreria fornisce un accesso comodo alla Claude API da TypeScript o JavaScript.

Installazione

npm install @anthropic-ai/sdk

Requisiti

È supportato TypeScript >= 4.9.

Sono supportati i seguenti runtime:

• Node.js 20 LTS o versioni successive (non EOL).
• Deno v1.28.0 o superiore.
• Bun 1.0 o successivo.
• Cloudflare Workers.
• Vercel Edge Runtime.
• Jest 28 o superiore con l'ambiente "node" ("jsdom" non è supportato al momento).
• Nitro v2.6 o superiore.
• Browser web: disabilitati per impostazione predefinita per evitare di esporre le tue credenziali API segrete (consulta le best practice per le chiavi API). Abilita il supporto per i browser impostando esplicitamente dangerouslyAllowBrowser su true.

Nota che React Native non è supportato al momento.

Se sei interessato ad altri ambienti di runtime, apri o vota una issue nel repository GitHub.

Utilizzo

const client = new Anthropic({
  apiKey: process.env["ANTHROPIC_API_KEY"] // This is the default and can be omitted
});

const message = await client.messages.create({
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  model: "claude-opus-5"
});

for (const block of message.content) {
  if (block.type === "text") {
    console.log(block.text);
  }
}

Per le opzioni di autenticazione, inclusa la Workload Identity Federation, consulta Autenticazione. Se la tua chiave API è una chiave personale o di account di servizio con accesso a più workspace, imposta l'ID del workspace nell'header di richiesta anthropic-workspace-id; Seleziona un workspace mostra l'opzione per singola richiesta per questo SDK.

Tipi di richiesta e risposta

Questa libreria include definizioni TypeScript per tutti i parametri di richiesta e i campi di risposta. Puoi importarli e usarli in questo modo:

const client = new Anthropic({
  apiKey: process.env["ANTHROPIC_API_KEY"] // This is the default and can be omitted
});

const params: Anthropic.MessageCreateParams = {
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  model: "claude-opus-5"
};
const message: Anthropic.Message = await client.messages.create(params);

La documentazione per ogni metodo, parametro di richiesta e campo di risposta è disponibile nelle docstring e appare al passaggio del mouse nella maggior parte degli editor moderni.

Conteggio dei token

Puoi vedere l'utilizzo esatto per una determinata richiesta tramite la proprietà di risposta usage, ad esempio:

const message = await client.messages.create(/* ... */);
console.log(message.usage);
// { input_tokens: 25, output_tokens: 13 }

Risposte in streaming

L'SDK fornisce supporto per le risposte in "streaming" (streaming) utilizzando Server Sent Events (SSE).

const client = new Anthropic();

const stream = await client.messages.create({
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  model: "claude-opus-5",
  stream: true
});
for await (const messageStreamEvent of stream) {
  console.log(messageStreamEvent.type);
}

Se hai bisogno di annullare uno stream, puoi uscire dal ciclo con break oppure chiamare stream.controller.abort().

Helper per lo streaming

Questa libreria fornisce diverse comodità per lo streaming dei messaggi, ad esempio:

const anthropic = new Anthropic();

const stream = anthropic.messages
  .stream({
    model: "claude-opus-5",
    max_tokens: 1024,
    messages: [
      {
        role: "user",
        content: "Say hello there!"
      }
    ]
  })
  .on("text", (text) => {
    console.log(text);
  });

const message = await stream.finalMessage();
console.log(message);

Lo streaming con client.messages.stream(...) espone vari helper per tua comodità, inclusi gestori di eventi e accumulo.

In alternativa, puoi usare client.messages.create({ ..., stream: true }) che restituisce solo un iterabile asincrono degli eventi nello stream e quindi utilizza meno memoria (non costruisce per te un oggetto messaggio finale).

Helper per gli strumenti

Questo SDK fornisce helper per semplificare la creazione e l'esecuzione di strumenti nella Messages API. Puoi usare schemi Zod o JSON Schema per descrivere l'input di uno strumento. Puoi quindi eseguire tali strumenti usando il metodo client.beta.messages.toolRunner(). Questo metodo si occupa di passare gli input generati dal modello scelto allo strumento corretto e di restituire il risultato al modello.

Per maggiori dettagli sul "tool use" (uso degli strumenti), consulta Uso degli strumenti con Claude.

import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
import { z } from "zod";

const anthropic = new Anthropic();

const weatherTool = betaZodTool({
  name: "get_weather",
  inputSchema: z.object({
    location: z.string()
  }),
  description: "Get the current weather in a given location",
  run: (input) => {
    return `The weather in ${input.location} is foggy and 60°F`;
  }
});

const finalMessage = await anthropic.beta.messages.toolRunner({
  model: "claude-opus-5",
  max_tokens: 1000,
  messages: [{ role: "user", content: "What is the weather in San Francisco?" }],
  tools: [weatherTool]
});

console.log(finalMessage.content);

Errori degli strumenti

Per segnalare al modello un errore proveniente da uno strumento, lancia un ToolError dalla funzione run. A differenza di un semplice Error, ToolError accetta blocchi di contenuto, permettendoti di includere immagini o altri contenuti strutturati nella risposta di errore:

import { ToolError } from "@anthropic-ai/sdk/lib/tools/BetaRunnableTool";

const screenshotTool = betaZodTool({
  name: "take_screenshot",
  inputSchema: z.object({ url: z.string() }),
  run: async (input) => {
    if (!isValidUrl(input.url)) {
      throw new ToolError(`Invalid URL: ${input.url}`);
    }
    const result = await takeScreenshot(input.url);
    if (result.error) {
      // Includi lo screenshot dell'errore così il modello può vedere cosa è andato storto
      throw new ToolError([
        { type: "text", text: `Failed to load page: ${result.error}` },
        {
          type: "image",
          source: { type: "base64", data: result.screenshot, media_type: "image/png" }
        }
      ]);
    }
    return {
      type: "image",
      source: { type: "base64", data: result.screenshot, media_type: "image/png" }
    };
  }
});

Se viene lanciato un semplice Error, il messaggio verrà convertito in un blocco di contenuto di testo.

Uso degli strumenti

Questo SDK fornisce supporto per l'uso degli strumenti, noto anche come function calling. Per maggiori dettagli, consulta Uso degli strumenti con Claude.

Helper MCP

Questo SDK fornisce helper per l'integrazione con i server Model Context Protocol (MCP). Questi helper convertono i tipi MCP in tipi della Claude API, riducendo il codice boilerplate quando si lavora con strumenti, prompt e risorse MCP.

import {
  mcpTools,
  mcpMessages,
  mcpResourceToContent,
  mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const anthropic = new Anthropic();

// Connettiti a un server MCP
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);

// Usa i prompt MCP
const { messages } = await mcpClient.getPrompt({ name: "my-prompt" });
const response = await anthropic.beta.messages.create({
  model: "claude-opus-5",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});
console.log(response.content);

// Usa gli strumenti MCP con toolRunner
const { tools } = await mcpClient.listTools();
const finalMessage = await anthropic.beta.messages.toolRunner({
  model: "claude-opus-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Use the available tools" }],
  tools: mcpTools(tools, mcpClient)
});
console.log(finalMessage.content);

// Usa le risorse MCP come contenuto
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
await anthropic.beta.messages.create({
  model: "claude-opus-5",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        mcpResourceToContent(resource),
        { type: "text", text: "Summarize this document" }
      ]
    }
  ]
});

// Carica le risorse MCP come file
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
await anthropic.files.upload({ file: mcpResourceToFile(fileResource) });

Gestione degli errori MCP

Le funzioni di conversione lanciano UnsupportedMCPValueError se un valore MCP non è supportato dalla Claude API (ad esempio, tipo di contenuto non supportato, tipo MIME non supportato, link a risorsa non http/https).

Batch di messaggi

Questo SDK fornisce supporto per l'elaborazione batch sotto il namespace client.messages.batches.

Creazione di un batch

Message Batches accetta un array di richieste, in cui ogni oggetto ha un identificatore custom_id e gli stessi identici params di richiesta della Messages API standard:

const batch = await client.messages.batches.create({
  requests: [
    {
      custom_id: "my-first-request",
      params: {
        model: "claude-opus-5",
        max_tokens: 1024,
        messages: [{ role: "user", content: "Hello, world" }]
      }
    },
    {
      custom_id: "my-second-request",
      params: {
        model: "claude-opus-5",
        max_tokens: 1024,
        messages: [{ role: "user", content: "Hi again, friend" }]
      }
    }
  ]
});

Ottenere i risultati da un batch

Una volta che un Message Batch è stato elaborato, come indicato da .processing_status === 'ended', puoi accedere ai risultati con .batches.results()

const results = await client.messages.batches.results(batch.id);
for await (const entry of results) {
  if (entry.result.type === "succeeded") {
    console.log(entry.result.message.content);
  }
}

Caricamento di file

I parametri di richiesta che corrispondono a caricamenti di file possono essere passati in molte forme diverse:

• File (o un oggetto con la stessa struttura)
• una Response di fetch (o un oggetto con la stessa struttura)
• un fs.ReadStream
• il valore restituito dall'helper toFile

Imposta esplicitamente il content-type, poiché la Files API non lo dedurrà per te:

import fs from "node:fs";
import Anthropic, { toFile } from "@anthropic-ai/sdk";

const client = new Anthropic();

// Se hai accesso a `fs` di Node, usa `fs.createReadStream()`:
await client.files.upload({
  file: await toFile(fs.createReadStream("/path/to/file"), undefined, {
    type: "application/json"
  })
});

// Oppure, se disponi dell'API web `File`, puoi passare un'istanza di `File`:
await client.files.upload({
  file: new File(["my bytes"], "file.txt", { type: "text/plain" })
});
// Puoi anche passare una `Response` di `fetch`:
await client.files.upload({
  file: await fetch("https://somesite/file")
});

// Oppure un `Buffer` / `Uint8Array`
await client.files.upload({
  file: await toFile(Buffer.from("my bytes"), "file", { type: "text/plain" })
});
await client.files.upload({
  file: await toFile(new Uint8Array([0, 1, 2]), "file", { type: "text/plain" })
});

Gestione degli errori

Quando la libreria non riesce a connettersi all'API, o se l'API restituisce un codice di stato non di successo (ovvero una risposta 4xx o 5xx), viene lanciata una sottoclasse di APIError:

const message = await client.messages
  .create({
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5"
  })
  .catch(async (err) => {
    if (err instanceof Anthropic.APIError) {
      console.log(err.status); // 400
      console.log(err.name); // BadRequestError
      console.log(err.headers); // {server: 'nginx', ...}
    } else {
      throw err;
    }
  });

I codici di errore sono i seguenti:

ID delle richieste

Per maggiori informazioni sul debug delle richieste, consulta ID richiesta.

Tutte le risposte oggetto nell'SDK forniscono una proprietà _request_id che viene aggiunta dall'header di risposta request-id, in modo che tu possa registrare rapidamente le richieste fallite e segnalarle ad Anthropic.

const message = await client.messages.create({
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  model: "claude-opus-5"
});
console.log(message._request_id); // req_018EeWyXxfu5pfWkrYcMdjWG

Tentativi ripetuti

Alcuni errori vengono automaticamente ritentati 2 volte per impostazione predefinita, con un breve backoff esponenziale. Gli errori di connessione (ad esempio, a causa di un problema di connettività di rete), 408 Request Timeout, 409 Conflict, 429 Rate Limit e gli errori interni >=500 vengono tutti ritentati per impostazione predefinita.

Puoi usare l'opzione maxRetries per configurare o disabilitare questo comportamento:

// Configura il valore predefinito per tutte le richieste:
const client = new Anthropic({
  maxRetries: 0 // default is 2
});

// Oppure, configura per singola richiesta:
await client.messages.create(
  {
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5"
  },
  { maxRetries: 5 }
);

Timeout

Per impostazione predefinita le richieste vanno in timeout dopo 10 minuti. Tuttavia, se hai specificato un valore max_tokens elevato e non stai usando lo streaming, il timeout predefinito verrà calcolato dinamicamente usando la formula:

const minimum = 10 * 60;
const calculated = (60 * 60 * maxTokens) / 128_000;
return calculated < minimum ? minimum * 1000 : calculated * 1000;

che risulterà in un timeout fino a 60 minuti, scalato in base al parametro max_tokens, a meno che non venga sovrascritto a livello di richiesta o di client.

Puoi configurarlo con un'opzione timeout:

// Configura il valore predefinito per tutte le richieste:
const client = new Anthropic({
  timeout: 20 * 1000 // 20 seconds (default is 10 minutes)
});

// Sovrascrivi per singola richiesta:
await client.messages.create(
  {
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5"
  },
  { timeout: 5 * 1000 }
);

In caso di timeout, viene lanciato un APIConnectionTimeoutError.

Nota che le richieste che vanno in timeout vengono ritentate due volte per impostazione predefinita.

Richieste lunghe

Evita di impostare un valore max_tokens elevato senza usare lo streaming. Alcune reti potrebbero interrompere le connessioni inattive dopo un certo periodo di tempo, il che può causare il fallimento della richiesta o un timeout senza ricevere una risposta da Anthropic.

Questo SDK lancia inoltre un errore se si prevede che una richiesta non in streaming duri più di circa 10 minuti. Passare stream: true o sovrascrivere l'opzione timeout a livello di client o di richiesta disabilita questo errore.

Una "latency" (latenza) prevista della richiesta superiore al timeout per una richiesta non in streaming comporterà la chiusura della connessione da parte del client e un nuovo tentativo senza ricevere una risposta.

Quando supportato dall'implementazione di fetch, l'SDK imposta un'opzione TCP socket keep-alive per ridurre l'impatto dei timeout delle connessioni inattive su alcune reti. Questo può essere sovrascritto configurando un proxy personalizzato.

Paginazione automatica

I metodi di elenco nella Claude API sono paginati. Puoi usare la sintassi for await ... of per iterare sugli elementi attraverso tutte le pagine:

async function fetchAllMessageBatches() {
  const allMessageBatches = [];
  // Recupera automaticamente altre pagine secondo necessità.
  for await (const messageBatch of client.messages.batches.list({ limit: 20 })) {
    allMessageBatches.push(messageBatch);
  }
  return allMessageBatches;
}

In alternativa, puoi richiedere una singola pagina alla volta:

let page = await client.messages.batches.list({ limit: 20 });
for (const messageBatch of page.data) {
  console.log(messageBatch);
}

// Sono disponibili metodi di utilità per la paginazione manuale:
while (page.hasNextPage()) {
  page = await page.getNextPage();
  // ...
}

Header predefiniti

L'SDK invia automaticamente l'header anthropic-version impostato su 2023-06-01.

Se necessario, puoi sovrascriverlo impostando header predefiniti per singola richiesta.

Tieni presente che farlo potrebbe comportare tipi errati e altri comportamenti imprevisti o non definiti nell'SDK.

const client = new Anthropic();

const message = await client.messages.create(
  {
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5"
  },
  { headers: { "anthropic-version": "My-Custom-Value" } }
);

Utilizzo avanzato

Accesso ai dati grezzi della Response (ad esempio, gli header)

La Response "grezza" restituita da fetch() è accessibile tramite il metodo .asResponse() sul tipo APIPromise restituito da tutti i metodi. Questo metodo ritorna non appena vengono ricevuti gli header di una risposta di successo e non consuma il corpo della risposta, quindi sei libero di scrivere logica di parsing o di streaming personalizzata.

Puoi anche usare il metodo .withResponse() per ottenere la Response grezza insieme ai dati analizzati. A differenza di .asResponse(), questo metodo consuma il corpo, ritornando una volta che è stato analizzato.

const client = new Anthropic();

const response = await client.messages
  .create({
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5"
  })
  .asResponse();
console.log(response.headers.get("X-My-Header"));
console.log(response.statusText); // access the underlying Response object

const { data: message, response: raw } = await client.messages
  .create({
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5"
  })
  .withResponse();
console.log(raw.headers.get("X-My-Header"));
console.log(message.content);

Logging

Livelli di log

Puoi configurare il livello di log in due modi:

1. Tramite la variabile d'ambiente ANTHROPIC_LOG
2. Usando l'opzione client logLevel (sovrascrive la variabile d'ambiente se impostata)

const client = new Anthropic({
  logLevel: "debug" // Show all log messages
});

Livelli di log disponibili, dal più al meno dettagliato:

• 'debug' - Mostra messaggi di debug, info, avvisi ed errori
• 'info' - Mostra messaggi info, avvisi ed errori
• 'warn' - Mostra avvisi ed errori (predefinito)
• 'error' - Mostra solo gli errori
• 'off' - Disabilita tutto il logging

Al livello 'debug', tutte le richieste e risposte HTTP vengono registrate, inclusi header e corpi. Alcuni header relativi all'autenticazione vengono oscurati, ma i dati sensibili nei corpi di richiesta e risposta potrebbero comunque essere visibili.

Logger personalizzato

Per impostazione predefinita, questa libreria scrive i log su globalThis.console. Puoi anche fornire un logger personalizzato. La maggior parte delle librerie di logging è supportata, incluse pino, winston, bunyan, consola, signale e @std/log. Se il tuo logger non funziona, apri una issue.

Quando fornisci un logger personalizzato, l'opzione logLevel controlla comunque quali messaggi vengono emessi; i messaggi al di sotto del livello configurato non verranno inviati al tuo logger.

import pino from "pino";

const logger = pino();

const client = new Anthropic({
  logger: logger.child({ name: "Anthropic" }),
  logLevel: "debug" // Send all messages to pino, allowing it to filter
});

Effettuare richieste personalizzate/non documentate

Questa libreria è tipizzata per un accesso comodo all'API documentata. Se hai bisogno di accedere a endpoint, parametri o proprietà di risposta non documentati, la libreria può comunque essere utilizzata.

Endpoint non documentati

Per effettuare richieste a endpoint non documentati, puoi usare client.get, client.post e altri verbi HTTP. Le opzioni del client, come i tentativi ripetuti, vengono rispettate quando si effettuano queste richieste.

await client.post("/some/path", {
  body: { some_prop: "foo" },
  query: { some_query_arg: "bar" }
});

Parametri di richiesta non documentati

Per effettuare richieste usando parametri non documentati, puoi usare // @ts-expect-error sul parametro non documentato. Questa libreria non verifica a runtime che la richiesta corrisponda al tipo, quindi qualsiasi valore extra che invii verrà inviato così com'è.

client.messages.create({
  // ...
  // @ts-expect-error baz is not yet public
  baz: "undocumented option"
});

Per le richieste con il verbo GET, eventuali parametri extra saranno nella query; tutte le altre richieste invieranno il parametro extra nel corpo.

Se vuoi inviare esplicitamente un argomento extra, puoi farlo con le opzioni di richiesta query, body e headers.

Proprietà di risposta non documentate

Per accedere a proprietà di risposta non documentate, puoi accedere all'oggetto risposta con // @ts-expect-error sull'oggetto risposta, oppure effettuare il cast dell'oggetto risposta al tipo richiesto. Come per i parametri di richiesta, l'SDK non valida né rimuove le proprietà extra dalla risposta dell'API.

Personalizzazione del client fetch

Per impostazione predefinita, questa libreria si aspetta che sia definita una funzione fetch globale.

Se vuoi usare una funzione fetch diversa, puoi applicare un polyfill alla globale:

import fetch from "my-fetch";

globalThis.fetch = fetch;

Oppure passarla al client:

import fetch from "my-fetch";

const client = new Anthropic({ fetch });

Opzioni di fetch

Se vuoi impostare opzioni fetch personalizzate senza sovrascrivere la funzione fetch, puoi fornire un oggetto fetchOptions quando crei il client o effettui una richiesta. (Le opzioni specifiche della richiesta sovrascrivono le opzioni del client.)

const client = new Anthropic({
  fetchOptions: {
    // opzioni `RequestInit`
  }
});

Configurazione dei proxy

Per modificare il comportamento del proxy, puoi fornire fetchOptions personalizzate che aggiungono alle richieste opzioni proxy specifiche del runtime:

import * as undici from "undici";

const proxyAgent = new undici.ProxyAgent("http://localhost:8888");
const client = new Anthropic({
  fetchOptions: {
    dispatcher: proxyAgent
  }
});

Funzionalità beta

Le funzionalità beta sono disponibili prima del rilascio generale per raccogliere feedback anticipati e testare nuove funzionalità. Puoi verificare la disponibilità di tutte le capacità e gli strumenti di Claude nella panoramica su come costruire con Claude.

Puoi accedere alla maggior parte delle funzionalità beta dell'API tramite la proprietà beta del client. Per abilitare una particolare funzionalità beta, devi aggiungere l'header beta appropriato al campo betas quando crei un messaggio.

Ad esempio, per abilitare la modifica del contesto:

const client = new Anthropic();
const response = await client.beta.messages.create({
  model: "claude-opus-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  betas: ["context-management-2025-06-27"]
});

Supporto dei runtime

Integrazioni con le piattaforme

L'SDK TypeScript supporta le seguenti piattaforme:

• Agent Platform: npm install @anthropic-ai/vertex-sdk: fornisce il client AnthropicVertex
• Bedrock: npm install @anthropic-ai/bedrock-sdk: fornisce il client AnthropicBedrockMantle e AnthropicBedrock per il percorso bedrock-runtime
• Claude Platform su AWS: npm install @anthropic-ai/aws-sdk: fornisce il client AnthropicAws. Passa workspaceId al costruttore oppure imposta la variabile d'ambiente ANTHROPIC_AWS_WORKSPACE_ID. Disponibile in beta.
• Foundry: npm install @anthropic-ai/foundry-sdk: fornisce il client AnthropicFoundry

Usa AnthropicBedrockMantle per i nuovi progetti; AnthropicBedrock rimane disponibile per le applicazioni esistenti che utilizzano l'API InvokeModel di Bedrock.

Versionamento semantico

Questo pacchetto segue generalmente le convenzioni SemVer, anche se alcune modifiche non retrocompatibili potrebbero essere rilasciate come versioni minori:

1. Modifiche che riguardano solo i tipi statici, senza alterare il comportamento a runtime.
2. Modifiche agli interni della libreria che sono tecnicamente pubblici ma non destinati o documentati per l'uso esterno.
3. Modifiche che non si prevede abbiano un impatto sulla grande maggioranza degli utenti nella pratica.

La retrocompatibilità viene presa seriamente per garantire che tu possa contare su un'esperienza di aggiornamento senza problemi.

Domande frequenti

Consulta il repository GitHub per FAQ, issue e supporto della community.

Risorse aggiuntive

• Repository GitHub
• Riferimento API
• Streaming dei messaggi
• Uso degli strumenti con Claude