---
title: TypeScript SDK
url: https://platform.claude.com/docs/it/cli-sdks-libraries/sdks/typescript
description: Installa e configura l'SDK TypeScript di Anthropic per ambienti Node.js, Deno, Bun e browser
---

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

<Info>
  Per la documentazione delle funzionalità dell'API con esempi di codice, consulta il [riferimento API](https://platform.claude.com/docs/it/api/overview). Questa pagina tratta le funzionalità e la configurazione specifiche dell'SDK TypeScript.
</Info>

## Installazione

```bash
npm install @anthropic-ai/sdk
```

## Requisiti

È supportato TypeScript >= 5.0.

Sono supportati i seguenti runtime:

* Node.js 20 LTS o versioni successive ([non-EOL](https://endoflife.date/nodejs)).
* 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](https://support.claude.com/en/articles/9767949-api-key-best-practices-keeping-your-keys-safe-and-secure)). Abilita il supporto per i browser impostando esplicitamente `dangerouslyAllowBrowser` su `true`.

Tieni presente che React Native non è supportato al momento.

Se sei interessato ad altri ambienti di runtime, apri o vota una issue nel [repository GitHub](https://github.com/anthropics/anthropic-sdk-typescript).

## Utilizzo

```typescript
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-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](https://platform.claude.com/docs/it/manage-claude/authentication). Se la tua chiave API è una [chiave personale o di account di servizio](https://platform.claude.com/docs/it/manage-claude/authentication#key-types) che non è limitata a un workspace, imposta l'ID del workspace nell'header di richiesta `anthropic-workspace-id`; [Selezionare un workspace](https://platform.claude.com/docs/it/manage-claude/authentication#select-a-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 importarle e usarle in questo modo:

```typescript
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-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:

```typescript
const message = await client.messages.create({
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  model: "claude-opus-5-5"
});
console.log(message.usage);
// { input_tokens: 25, output_tokens: 13 }
```

## Risposte in streaming

L'SDK fornisce supporto per le risposte in streaming utilizzando i "Server-Sent Events" (eventi inviati dal server), o SSE.

```typescript
const client = new Anthropic();

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

Se devi annullare uno stream, puoi usare `break` per uscire dal ciclo oppure chiamare `stream.controller.abort()`.

## Helper per lo streaming

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

```typescript
const anthropic = new Anthropic();

const stream = anthropic.messages
  .stream({
    model: "claude-opus-5-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 un oggetto messaggio finale per te).

## 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 sull'uso degli strumenti, consulta [Uso degli strumenti con Claude](https://platform.claude.com/docs/it/agents-and-tools/tool-use/overview). Per eseguire lo strumento browser use o lo strumento computer use con questo SDK, consulta [Browser e computer use con i toolset dell'SDK](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-sdk).

```typescript
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-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 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:

```typescript
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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/overview).

## Helper MCP

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

<Tip>
  La Claude API supporta anche un [parametro `mcp_servers`](https://platform.claude.com/docs/it/agents-and-tools/mcp-connector) che consente a Claude di connettersi direttamente a server MCP remoti. Usa `mcp_servers` quando hai server remoti accessibili tramite URL e ti serve solo il supporto per gli strumenti. Usa gli helper MCP quando ti servono server MCP locali, prompt, risorse o un maggiore controllo sulla connessione MCP.
</Tip>

```typescript
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-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-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-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](https://platform.claude.com/docs/it/build-with-claude/batch-processing) nel 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:

```typescript
const batch = await client.messages.batches.create({
  requests: [
    {
      custom_id: "my-first-request",
      params: {
        model: "claude-opus-5-5",
        max_tokens: 1024,
        messages: [{ role: "user", content: "Hello, world" }]
      }
    },
    {
      custom_id: "my-second-request",
      params: {
        model: "claude-opus-5-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()`

```typescript
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 tipo di contenuto, poiché la Files API non lo dedurrà per te:

```typescript
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 hai l'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 di errore (ovvero, una risposta 4xx o 5xx), viene lanciata una sottoclasse di `APIError`:

```typescript
const message = await client.messages
  .create({
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5-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:

| Codice di stato | Tipo di errore             |
| --------------- | -------------------------- |
| 400             | `BadRequestError`          |
| 401             | `AuthenticationError`      |
| 403             | `PermissionDeniedError`    |
| 404             | `NotFoundError`            |
| 409             | `ConflictError`            |
| 422             | `UnprocessableEntityError` |
| 429             | `RateLimitError`           |
| >=500           | `InternalServerError`      |
| N/A             | `APIConnectionError`       |

## ID delle richieste

> Per maggiori informazioni sul debug delle richieste, consulta [ID della richiesta](https://platform.claude.com/docs/it/api/errors#request-id).

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

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

## Tentativi ripetuti

Alcuni errori vengono ritentati automaticamente 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:

```typescript
// 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-5"
  },
  { maxRetries: 5 }
);
```

## Timeout

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

```typescript
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`:

```typescript
// 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-5"
  },
  { timeout: 5 * 1000 }
);
```

In caso di timeout, viene lanciato un `APIConnectionTimeoutError`.

Tieni presente che le richieste che scadono vengono [ritentate due volte per impostazione predefinita](https://platform.claude.com/docs/it/cli-sdks-libraries/sdks/typescript#retries).

## Richieste lunghe

<Warning>
  Valuta l'uso della [Messages API](https://platform.claude.com/docs/it/cli-sdks-libraries/sdks/typescript#streaming-responses) in streaming per le richieste di lunga durata.
</Warning>

Evita di impostare un valore elevato di `max_tokens` 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 il suo [timeout](https://platform.claude.com/docs/it/cli-sdks-libraries/sdks/typescript#timeouts) 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](https://platform.claude.com/docs/it/cli-sdks-libraries/sdks/typescript#timeouts) l'opzione `timeout` a livello di client o di richiesta disabilita questo errore.

Una "latency" (latenza) prevista della richiesta superiore al [timeout](https://platform.claude.com/docs/it/cli-sdks-libraries/sdks/typescript#timeouts) per una richiesta non in streaming farà sì che il client termini la connessione e ritenti senza ricevere una risposta.

Quando supportato dall'implementazione di `fetch`, l'SDK imposta un'opzione [TCP socket keep-alive](https://tldp.org/HOWTO/TCP-Keepalive-HOWTO/overview.html) per ridurre l'impatto dei timeout delle connessioni inattive su alcune reti. Questa può essere [sovrascritta](https://platform.claude.com/docs/it/cli-sdks-libraries/sdks/typescript#configuring-proxies) 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 di tutte le pagine:

```typescript
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:

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

// Sono disponibili metodi di utilità per paginare manualmente:
while (page.hasNextPage()) {
  page = await page.getNextPage();
  // ...
}
```

## Header predefiniti

L'SDK invia automaticamente l'header `anthropic-version` impostato su la versione dell'API per questa versione major dell'SDK (consulta [Versionamento semantico](https://platform.claude.com/docs/it/cli-sdks-libraries/sdks/typescript#semantic-versioning)).

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

Tieni presente che ciò potrebbe causare tipi errati e altri comportamenti imprevisti o non definiti nell'SDK.

```typescript
const client = new Anthropic();

const message = await client.messages.create(
  {
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5-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 restituisce il controllo non appena vengono ricevuti gli header di una risposta riuscita e non consuma il corpo della risposta, quindi sei libero di scrivere logica personalizzata di parsing o di 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 il controllo una volta che è stato analizzato.

```typescript
const client = new Anthropic();

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

### Logging

<Warning>
  Tutti i messaggi di log sono destinati esclusivamente al debug. Il formato e il contenuto dei messaggi di log possono cambiare tra una release e l'altra.
</Warning>

#### Livelli di log

Puoi configurare il livello di log in due modi:

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

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

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

* `'debug'` - Mostra messaggi di debug, informazioni, avvisi ed errori
* `'info'` - Mostra messaggi informativi, 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 le risposte HTTP vengono registrate, inclusi header e corpi. Alcuni header relativi all'autenticazione vengono oscurati, ma i dati sensibili nei corpi delle richieste e delle risposte potrebbero essere comunque 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, tra cui [pino](https://www.npmjs.com/package/pino), [winston](https://www.npmjs.com/package/winston), [bunyan](https://www.npmjs.com/package/bunyan), [consola](https://www.npmjs.com/package/consola), [signale](https://www.npmjs.com/package/signale) e [@std/log](https://jsr.io/@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.

```typescript
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
});
```

### Tracciamento OpenTelemetry

Quando la tua applicazione registra un tracer provider OpenTelemetry, l'SDK emette uno span per ogni richiesta che invia. Per inviare gli span alla tua piattaforma di osservabilità, consulta [Configurare OpenTelemetry con il Claude SDK](https://platform.claude.com/docs/it/manage-claude/opentelemetry/sdk).

### Effettuare richieste personalizzate/non documentate

Questa libreria è tipizzata per un accesso comodo all'API documentata. Se devi 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 gli altri verbi HTTP. Le opzioni del client, come i tentativi ripetuti, vengono rispettate quando si effettuano queste richieste.

```typescript
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 aggiuntivo che invii verrà inviato così com'è.

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

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

Se vuoi inviare esplicitamente un argomento aggiuntivo, 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 usando `// @ts-expect-error` sull'oggetto risposta, oppure eseguire il cast dell'oggetto risposta al tipo richiesto. Come per i parametri di richiesta, l'SDK non convalida né rimuove le proprietà aggiuntive 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 a quella globale:

```typescript
import fetch from "my-fetch";

globalThis.fetch = fetch;
```

Oppure passarla al client:

```typescript
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` durante la creazione del client o l'invio di una richiesta. (Le opzioni specifiche della richiesta sovrascrivono le opzioni del client.)

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

### Configurazione dei proxy

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

<Tabs>
  <Tab title="Node.js">
    ```typescript
    import * as undici from "undici";

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

  <Tab title="Bun">
    ```typescript
    const client = new Anthropic({
      fetchOptions: {
        proxy: "http://localhost:8888"
      }
    });
    ```
  </Tab>

  <Tab title="Deno">
    ```typescript
    import Anthropic from "npm:@anthropic-ai/sdk";

    const httpClient = Deno.createHttpClient({ proxy: { url: "http://localhost:8888" } });
    const client = new Anthropic({
      fetchOptions: {
        client: httpClient
      }
    });
    ```
  </Tab>
</Tabs>

## Funzionalità beta

Le funzionalità beta sono disponibili prima del rilascio generale per ottenere feedback anticipati e testare nuove funzionalità. Puoi verificare la disponibilità di tutte le capacità e gli strumenti di Claude nella [Panoramica delle funzionalità](https://platform.claude.com/docs/it/build-with-claude/overview).

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](https://platform.claude.com/docs/it/api/beta-headers) appropriato al campo `betas` durante la creazione di un messaggio.

Ad esempio, per abilitare la [modifica del contesto](https://platform.claude.com/docs/it/build-with-claude/context-editing):

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

## Supporto dei runtime

<Accordion title="Utilizzo nel browser">
  Abilitare l'opzione `dangerouslyAllowBrowser` può essere pericoloso perché espone le tue credenziali API segrete nel codice lato client. I browser web sono intrinsecamente meno sicuri degli ambienti server. Qualsiasi utente con accesso al browser può potenzialmente ispezionare, estrarre e utilizzare impropriamente queste credenziali. Ciò potrebbe portare ad accessi non autorizzati con le tue credenziali e potenzialmente compromettere dati o funzionalità sensibili.

  **Quando potrebbe non essere pericoloso?**

  In alcuni scenari, abilitare il supporto per i browser potrebbe non comportare rischi significativi:

  * **Strumenti interni:** se l'applicazione viene utilizzata esclusivamente all'interno di un ambiente interno controllato in cui gli utenti sono affidabili, il rischio di esposizione delle credenziali può essere mitigato.
  * **Scopi di sviluppo o debug:** abilitare temporaneamente questa funzionalità potrebbe essere accettabile, a condizione che le credenziali abbiano una breve durata, non vengano utilizzate anche in ambienti di produzione o vengano ruotate frequentemente.
</Accordion>

## Integrazioni con le piattaforme

<Note>
  Per guide dettagliate alla configurazione delle piattaforme con esempi di codice, consulta:

  * [Amazon Bedrock](https://platform.claude.com/docs/it/build-with-claude/claude-in-amazon-bedrock)
  * [Amazon Bedrock (Opus 4.6 e precedenti)](https://platform.claude.com/docs/it/build-with-claude/claude-on-amazon-bedrock-legacy)
  * [Claude Platform on AWS](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws)
  * [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/it/build-with-claude/claude-models-on-google-cloud/google-managed)
  * [Microsoft Foundry](https://platform.claude.com/docs/it/build-with-claude/claude-in-microsoft-foundry)

  Consulta anche [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/it/build-with-claude/claude-models-on-google-cloud/anthropic-managed).
</Note>

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 on 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 per le applicazioni esistenti che utilizzano l'API `InvokeModel` di Bedrock.

L'SDK TypeScript supporta anche Claude Models on Google Cloud (Anthropic managed) tramite il client `AnthropicGoogleCloud`. Questo client è in beta. Per installarlo, esegui `npm install @anthropic-ai/google-cloud-sdk`. Passa `workspaceId` al costruttore oppure imposta la variabile d'ambiente `ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID`. Consulta [Risoluzione di progetto, location e workspace](https://platform.claude.com/docs/it/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution) per sapere come il client risolve l'ID del workspace.

## Versionamento semantico

Ogni versione major di questo SDK invia per impostazione predefinita una versione dell'API nell'header `anthropic-version`, e una nuova versione major accompagna ogni nuova versione dell'API. La prima versione major che invia `2026-10-21` è la 1.0.0; consulta [Migrazione alla versione API 2026-10-21](https://platform.claude.com/docs/it/api/migration-2026-10-21#upgrade).

Questo pacchetto segue generalmente le convenzioni [SemVer](https://semver.org/spec/v2.0.0.html), anche se alcune modifiche non retrocompatibili potrebbero essere rilasciate come versioni minor:

1. Modifiche che riguardano solo i tipi statici, senza compromettere il comportamento a runtime.
2. Modifiche agli elementi 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 stragrande maggioranza degli utenti nella pratica.

La retrocompatibilità viene presa sul serio per garantire che tu possa contare su un'esperienza di aggiornamento senza intoppi.

## Domande frequenti

Consulta il [repository GitHub](https://github.com/anthropics/anthropic-sdk-typescript) per FAQ, issue e supporto della community.

## Risorse aggiuntive

* [Repository GitHub](https://github.com/anthropics/anthropic-sdk-typescript)
* [Riferimento API](https://platform.claude.com/docs/it/api/overview)
* [Streaming dei messaggi](https://platform.claude.com/docs/it/build-with-claude/streaming)
* [Uso degli strumenti con Claude](https://platform.claude.com/docs/it/agents-and-tools/tool-use/overview)