---
title: SDK TypeScript
url: https://platform.claude.com/docs/it/cli-sdks-libraries/sdks/typescript
description: Installa e configura l'SDK TypeScript di Anthropic per Node.js, Deno, Bun e ambienti 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 dell'SDK specifiche per 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`.

Nota 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) con accesso a più workspace, imposta l'ID del workspace nell'header di richiesta `anthropic-workspace-id`; [Seleziona 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 importarli e usarli 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 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:

```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 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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/overview). Per eseguire lo strumento di uso del browser o lo strumento di uso del computer con questo SDK, consulta [Uso del browser e del computer 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 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:

```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 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](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 disponi di server remoti accessibili tramite URL e hai bisogno solo del supporto per gli strumenti. Usa gli helper MCP quando hai bisogno di server MCP locali, prompt, risorse o di 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) 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:

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

```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 richiesta](https://platform.claude.com/docs/it/api/errors#request-id).

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.

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

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

```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`.

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

## Richieste lunghe

<Warning>
  Considera 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 `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 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 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](https://tldp.org/HOWTO/TCP-Keepalive-HOWTO/overview.html) per ridurre l'impatto dei timeout delle connessioni inattive su alcune reti. Questo può essere [sovrascritto](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 attraverso tutte le pagine:

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

```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 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.

```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 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.

```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 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, 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](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
});
```

### 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.

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

```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` quando crei il client o effettui una richiesta. (Le opzioni specifiche della richiesta sovrascrivono le opzioni del client.)

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

<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 l'abilitazione del 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 fidati, 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 siano di 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 su AWS](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws)
  * [Google Cloud](https://platform.claude.com/docs/it/build-with-claude/claude-on-vertex-ai)
  * [Microsoft Foundry](https://platform.claude.com/docs/it/build-with-claude/claude-in-microsoft-foundry)
</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 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](https://semver.org/spec/v2.0.0.html), 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 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)