SDK TypeScript

Questa libreria fornisce un accesso comodo all'API REST di Anthropic 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: disabilitato per impostazione predefinita per evitare di esporre le tue credenziali API segrete (consulta le best practice per le chiavi API). Abilita il supporto browser impostando esplicitamente dangerouslyAllowBrowser su true.

Nota che React Native non è supportato al momento.

Se sei interessato ad altri ambienti runtime, apri o vota una issue su 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-4-8"
});

console.log(message.content);

Per le opzioni di autenticazione, inclusa la Workload Identity Federation, consulta Autenticazione.

Tipi di richiesta e risposta

Questa libreria include definizioni TypeScript per tutti i parametri di richiesta e i campi di risposta. Puoi importarli e utilizzarli 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-4-8"
};
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 apparirà 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 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-4-8",
  stream: true
});
for await (const messageStreamEvent of stream) {
  console.log(messageStreamEvent.type);
}

Se hai bisogno di annullare uno stream, puoi usare break per uscire dal ciclo o chiamare stream.controller.abort().

Helper per lo streaming

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

const anthropic = new Anthropic();

const stream = anthropic.messages
  .stream({
    model: "claude-opus-4-8",
    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 accumulazione.

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 un oggetto messaggio finale per te).

Helper per gli strumenti

Questo SDK fornisce helper per semplificare la creazione e l'esecuzione di strumenti nell'API Messages. Puoi usare schemi Zod o JSON Schema per descrivere l'input di uno strumento. Puoi quindi eseguire questi strumenti utilizzando il metodo client.beta.messages.toolRunner(). Questo metodo gestirà il passaggio degli input generati dal modello scelto allo strumento corretto e il passaggio del risultato al modello.

Per maggiori dettagli sull'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-4-8",
  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 un errore da uno strumento al modello, lancia un ToolError dalla funzione run. A differenza di un semplice Error, ToolError accetta blocchi di contenuto, consentendoti 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 testuale.

Uso degli strumenti

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

Helper MCP

Questo SDK fornisce helper per l'integrazione con server Model Context Protocol (MCP). Questi helper convertono i tipi MCP in tipi dell'API Claude, 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-4-8",
  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-4-8",
  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-4-8",
  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.beta.files.upload({ file: mcpResourceToFile(fileResource) });

Gestione degli errori MCP

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

Batch di messaggi

Questo SDK fornisce supporto per l'API Message Batches sotto il namespace client.messages.batches.

Creazione di un batch

Message Batches accetta un array di richieste, dove ogni oggetto ha un identificatore custom_id e gli stessi identici params di richiesta dell'API Messages standard:

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

Ottenere i risultati da un batch

Una volta che un Message Batch è stato elaborato, 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é l'API dei file non lo dedurrà per te:

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

const client = new Anthropic();

// Se hai accesso a `fs` di Node, usa `fs.createReadStream()`:
await client.beta.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.beta.files.upload({
  file: new File(["my bytes"], "file.txt", { type: "text/plain" })
});
// Puoi anche passare una `Response` di `fetch`:
await client.beta.files.upload({
  file: await fetch("https://somesite/file")
});

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

Gestione degli errori

Quando la libreria non è in grado di connettersi all'API, o se l'API restituisce un codice di stato non di successo (cioè 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-4-8"
  })
  .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 Request ID.

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

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

Tentativi di ripetizione

Alcuni errori verranno 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-4-8"
  },
  { 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 utilizzando 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 configurare questo comportamento 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-4-8"
  },
  { timeout: 5 * 1000 }
);

In caso di timeout, viene lanciato un APIConnectionTimeoutError.

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

Richieste lunghe

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

Questo SDK lancerà anche 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 più lunga del timeout per una richiesta non in streaming farà sì che il client termini la connessione e riprovi senza ricevere una risposta.

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

Paginazione automatica

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

async function fetchAllMessageBatches() {
  const allMessageBatches = [];
  // Recupera automaticamente altre pagine quando necessario.
  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 forniti metodi di convenienza 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 causare 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-4-8"
  },
  { headers: { "anthropic-version": "My-Custom-Value" } }
);

Utilizzo avanzato

Accesso ai dati Response grezzi (ad esempio, header)

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

Puoi anche usare il metodo .withResponse() per ottenere la Response grezza insieme ai dati analizzati. A differenza di .asResponse(), questo metodo consuma il corpo, restituendo 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-4-8"
  })
  .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-4-8"
  })
  .withResponse();
console.log(raw.headers.get("X-My-Header"));
console.log(message.content);

Logging

Livelli di log

Il livello di log può essere configurato in due modi:

1. Tramite la variabile d'ambiente ANTHROPIC_LOG
2. Utilizzando 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 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 essere ancora visibili.

Logger personalizzato

Per impostazione predefinita, questa libreria registra 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 sul client, come i tentativi di ripetizione, verranno 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 utilizzando parametri non documentati, puoi usare // @ts-expect-error sul parametro non documentato. Questa libreria non valida 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, qualsiasi parametro extra sarà 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, o eseguire il cast dell'oggetto risposta al tipo richiesto. Come per i parametri di richiesta, l'SDK non valida né rimuove 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 fare il polyfill della globale:

import fetch from "my-fetch";

globalThis.fetch = fetch;

Oppure passarla al client:

import fetch from "my-fetch";

const client = new Anthropic({ fetch });

Opzioni 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 opzioni proxy specifiche del runtime alle richieste:

Funzionalità beta

Le funzionalità beta sono disponibili prima del rilascio generale per ottenere feedback anticipato e testare nuove funzionalità. Puoi verificare la disponibilità di tutte le capacità e gli strumenti di Claude nella panoramica di build with Claude.

Puoi accedere alla maggior parte delle funzionalità API beta 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 usare l'API Files:

const client = new Anthropic();
const response = await client.beta.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "Please summarize this document for me." },
        {
          type: "document",
          source: {
            type: "file",
            file_id: "file_abc123"
          }
        }
      ]
    }
  ],
  betas: ["files-api-2025-04-14"]
});

Supporto runtime

Integrazioni con piattaforme

L'SDK TypeScript supporta le seguenti piattaforme:

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

Usa AnthropicBedrockMantle per i nuovi progetti; AnthropicBedrock rimane 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 possono essere rilasciate come versioni minori:

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

La retrocompatibilità è presa seriamente per garantire che tu possa contare su un'esperienza di aggiornamento fluida.

Domande frequenti

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

Risorse aggiuntive

• Repository GitHub
• Riferimento API
• Messaggi in streaming
• Uso degli strumenti con Claude