---
title: C# SDK
url: https://platform.claude.com/docs/it/cli-sdks-libraries/sdks/csharp
description: Installa e configura l'SDK C# di Anthropic per applicazioni .NET con integrazione IChatClient
---

L'SDK C# di Anthropic fornisce un accesso comodo alla Claude API da applicazioni scritte in C#.

<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 C#.
</Info>

<Warning>
  A partire dalla versione 10+, il pacchetto `Anthropic` è ora l'SDK ufficiale di Anthropic per C#. Le versioni del pacchetto 3.X e precedenti erano in passato utilizzate per l'SDK sviluppato dalla community tryAGI, che è stato spostato in [`tryAGI.Anthropic`](https://www.nuget.org/packages/tryagi.Anthropic/). Se hai bisogno di continuare a usare il client precedente nel tuo progetto, aggiorna il riferimento al pacchetto a `tryAGI.Anthropic`.
</Warning>

## Installazione

Installa il pacchetto da [NuGet](https://www.nuget.org/packages/Anthropic):

```bash
dotnet add package Anthropic
```

## Requisiti

Questa libreria richiede .NET Standard 2.0 o versioni successive.

## Utilizzo

```csharp
using System;
using Anthropic;
using Anthropic.Models.Messages;

AnthropicClient client = new();

MessageCreateParams parameters = new()
{
    MaxTokens = 1024,
    Messages = [new UserMessageParam { Content = "Hello, Claude" }],
    Model = Model.ClaudeOpus5_5,
};

var message = await client.Messages.Create(parameters);

foreach (var block in message.Content)
{
    if (block.TryPickText(out var textBlock))
    {
        Console.WriteLine(textBlock.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.

## Configurazione del client

Configura il client usando le variabili d'ambiente:

```csharp
using Anthropic;

// Configurato tramite le variabili d'ambiente ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN e ANTHROPIC_BASE_URL
AnthropicClient client = new();
```

Oppure manualmente:

```csharp
using Anthropic;

AnthropicClient client = new() { ApiKey = "my-anthropic-api-key" };
```

Oppure usando una combinazione dei due approcci.

Consulta questa tabella per le opzioni disponibili:

| Proprietà   | Variabile d'ambiente   | Obbligatoria | Valore predefinito            |
| ----------- | ---------------------- | ------------ | ----------------------------- |
| `ApiKey`    | `ANTHROPIC_API_KEY`    | false        | -                             |
| `AuthToken` | `ANTHROPIC_AUTH_TOKEN` | false        | -                             |
| `BaseUrl`   | `ANTHROPIC_BASE_URL`   | true         | `"https://api.anthropic.com"` |

### Modificare la configurazione

Per usare temporaneamente una configurazione del client modificata, riutilizzando gli stessi pool di connessioni e di thread, chiama `WithOptions` su qualsiasi client o servizio:

```csharp
using System;

var message = await client
    .WithOptions(options =>
        options with
        {
            BaseUrl = "https://example.com",
            Timeout = TimeSpan.FromSeconds(42),
        }
    )
    .Messages.Create(parameters);

Console.WriteLine(message);
```

L'uso di un'[espressione `with`](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/operators/with-expression) semplifica la costruzione delle opzioni modificate.

Il metodo `WithOptions` non influisce sul client o sul servizio originale.

## Streaming

L'SDK definisce metodi che restituiscono stream di "chunk" (blocchi) di risposta, in cui ogni chunk può essere elaborato singolarmente non appena arriva, invece di attendere la risposta completa. I metodi di streaming corrispondono generalmente a risposte [SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) o [JSONL](https://jsonlines.org).

Un metodo di streaming ha sempre il suffisso `Streaming` nel nome, anche se non ha una variante non in streaming.

Questi metodi di streaming restituiscono [`IAsyncEnumerable`](https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.iasyncenumerable-1):

```csharp
using System;
using Anthropic.Models.Messages;

MessageCreateParams parameters = new()
{
    MaxTokens = 1024,
    Messages = [new UserMessageParam { Content = "Hello, Claude" }],
    Model = Model.ClaudeOpus5_5,
};

await foreach (var message in client.Messages.CreateStreaming(parameters))
{
    Console.WriteLine(message);
}
```

## Gestione degli errori

L'SDK genera tipi di eccezione personalizzati non controllati (unchecked):

* `AnthropicApiException`: classe base per gli errori dell'API. Consulta questa tabella per sapere quale sottoclasse di eccezione viene generata per ciascun codice di stato HTTP:

| Stato | Eccezione                                |
| ----- | ---------------------------------------- |
| 400   | `AnthropicBadRequestException`           |
| 401   | `AnthropicUnauthorizedException`         |
| 403   | `AnthropicForbiddenException`            |
| 404   | `AnthropicNotFoundException`             |
| 422   | `AnthropicUnprocessableEntityException`  |
| 429   | `AnthropicRateLimitException`            |
| 5xx   | `Anthropic5xxException`                  |
| altri | `AnthropicUnexpectedStatusCodeException` |

Inoltre, tutti gli errori 4xx ereditano da `Anthropic4xxException`.

* `AnthropicSseException`: generata per errori riscontrati durante lo streaming SSE dopo una risposta HTTP iniziale riuscita.

* `AnthropicIOException`: errori di rete di I/O.

* `AnthropicInvalidDataException`: impossibilità di interpretare dati analizzati correttamente. Ad esempio, quando si accede a una proprietà che dovrebbe essere obbligatoria, ma l'API l'ha inaspettatamente omessa dalla risposta.

* `AnthropicException`: classe base per tutte le eccezioni.

## Tentativi ripetuti

Per impostazione predefinita, l'SDK ripete automaticamente la richiesta 2 volte, con un breve backoff esponenziale tra le richieste.

Vengono ripetuti solo i seguenti tipi di errore:

* Errori di connessione (ad esempio, a causa di un problema di connettività di rete)
* 408 Request Timeout
* 409 Conflict
* 429 Rate Limit
* 5xx Internal

L'API può anche indicare esplicitamente all'SDK di ripetere o non ripetere una richiesta.

Per impostare un numero personalizzato di tentativi, configura il client usando la proprietà `MaxRetries`:

```csharp
using Anthropic;

AnthropicClient client = new() { MaxRetries = 3 };
```

Oppure configura una singola chiamata di metodo usando `WithOptions`:

```csharp
using System;

var message = await client
    .WithOptions(options =>
        options with { MaxRetries = 3 }
    )
    .Messages.Create(parameters);

Console.WriteLine(message);
```

## Timeout

Per impostazione predefinita, le richieste scadono dopo 10 minuti.

Per impostare un timeout personalizzato, configura il client usando l'opzione `Timeout`:

```csharp
using System;
using Anthropic;

AnthropicClient client = new() { Timeout = TimeSpan.FromSeconds(42) };
```

Oppure configura una singola chiamata di metodo usando `WithOptions`:

```csharp
using System;

var message = await client
    .WithOptions(options =>
        options with { Timeout = TimeSpan.FromSeconds(42) }
    )
    .Messages.Create(parameters);

Console.WriteLine(message);
```

## Paginazione

L'SDK definisce metodi che restituiscono elenchi paginati di risultati. Offre modi comodi per accedere ai risultati una pagina alla volta oppure elemento per elemento su tutte le pagine.

### Paginazione automatica

Per scorrere tutti i risultati su tutte le pagine, usa il metodo `Paginate`, che recupera automaticamente altre pagine secondo necessità. Il metodo restituisce un [`IAsyncEnumerable`](https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.iasyncenumerable-1):

```csharp
using System;

var page = await client.Messages.Batches.List(parameters);
await foreach (var item in page.Paginate())
{
    Console.WriteLine(item);
}
```

### Paginazione manuale

Per accedere ai singoli elementi della pagina e richiedere manualmente la pagina successiva, usa la proprietà `Items` e i metodi `HasNext` e `Next`:

```csharp
var page = await client.Messages.Batches.List();
while (true)
{
    foreach (var item in page.Items)
    {
        Console.WriteLine(item);
    }
    if (!page.HasNext())
    {
        break;
    }
    page = await page.Next();
}
```

## Validazione delle risposte

In rari casi, l'API può restituire una risposta che non corrisponde al tipo previsto. Per impostazione predefinita, in questo caso l'SDK non genera un'eccezione. Genera `AnthropicInvalidDataException` solo se accedi direttamente alla proprietà.

Se preferisci verificare in anticipo che la risposta sia completamente ben tipizzata, chiama `Validate`:

```csharp
var message = await client.Messages.Create(parameters);
message.Validate();
```

Oppure configura il client usando l'opzione `ResponseValidation`:

```csharp
using Anthropic;

AnthropicClient client = new() { ResponseValidation = true };
```

Oppure configura una singola chiamata di metodo usando `WithOptions`:

```csharp
using System;

var message = await client
    .WithOptions(options =>
        options with { ResponseValidation = true }
    )
    .Messages.Create(parameters);

Console.WriteLine(message);
```

## Integrazione con IChatClient

L'SDK fornisce un'implementazione dell'interfaccia `IChatClient` della libreria `Microsoft.Extensions.AI.Abstractions`. Ciò consente di usare `AnthropicClient` (e `Anthropic.Services.IBetaService`) con altre librerie che si integrano con queste astrazioni di base. Ad esempio, gli strumenti della libreria MCP C# SDK (`ModelContextProtocol`) possono essere usati direttamente con un `AnthropicClient` esposto tramite `IChatClient`.

```csharp
using Anthropic;
using Microsoft.Extensions.AI;
using ModelContextProtocol.Client;

// Configurato tramite le variabili d'ambiente ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN e ANTHROPIC_BASE_URL
AnthropicClient client = new();

IChatClient chatClient = client.AsIChatClient("claude-opus-5-5")
    .AsBuilder()
    .UseFunctionInvocation()
    .Build();

// Uso di McpClient dall'SDK C# di MCP
McpClient learningServer = await McpClient.CreateAsync(
    new HttpClientTransport(new() { Endpoint = new("https://learn.microsoft.com/api/mcp") }));

ChatOptions options = new() { Tools = [.. await learningServer.ListToolsAsync()] };

Console.WriteLine(await chatClient.GetResponseAsync("Tell me about IChatClient", options));
```

## Richieste e risposte

Per inviare una richiesta alla Claude API, crea un'istanza di una classe `Params` e passala al metodo del client corrispondente. Quando la risposta viene ricevuta, viene deserializzata in un'istanza di una classe C#.

Ad esempio, `client.Messages.Create` deve essere chiamato con un'istanza di `MessageCreateParams` e restituirà un'istanza di `Task<Message>`.

## Utilizzo avanzato

### Risposte binarie

L'SDK definisce metodi che restituiscono risposte binarie, usati per le risposte dell'API che non devono necessariamente essere analizzate, come i dati non JSON.

Questi metodi restituiscono `HttpResponse`:

```csharp
using System;
using Anthropic.Models.Files;

FileDownloadParams parameters = new() { FileID = "file_id" };

var response = await client.Files.Download(parameters);

Console.WriteLine(response);
```

Per salvare il contenuto della risposta in un file, o in qualsiasi [`Stream`](https://learn.microsoft.com/en-us/dotnet/api/system.io.stream), usa il metodo [`CopyToAsync`](https://learn.microsoft.com/en-us/dotnet/api/system.io.stream.copytoasync):

```csharp
using System.IO;

using var response = await client.Files.Download(parameters);
using var contentStream = await response.ReadAsStream();
using var fileStream = File.Open(path, FileMode.OpenOrCreate);
await contentStream.CopyToAsync(fileStream); // Or any other Stream
```

### Risposte grezze

L'SDK definisce metodi che deserializzano le risposte in istanze di classi C#. Per accedere alle intestazioni della risposta, al codice di stato o al corpo grezzo della risposta, anteponi `WithRawResponse` a qualsiasi chiamata di metodo HTTP su un client o servizio:

```csharp
var response = await client.WithRawResponse.Messages.Create(parameters);
var statusCode = response.StatusCode;
var headers = response.Headers;
```

È possibile accedere all'`HttpResponseMessage` grezzo anche tramite la proprietà `RawMessage`.

Per le risposte non in streaming, puoi deserializzare la risposta in un'istanza di una classe C#, se necessario:

```csharp
using System;
using Anthropic.Models.Messages;

var response = await client.WithRawResponse.Messages.Create(parameters);
Message deserialized = await response.Deserialize();
Console.WriteLine(deserialized);
```

Per le risposte in streaming, puoi deserializzare la risposta in un `IAsyncEnumerable`, se necessario:

```csharp
using System;

var response = await client.WithRawResponse.Messages.CreateStreaming(parameters);
await foreach (var item in response.Enumerate())
{
    Console.WriteLine(item);
}
```

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

Abilita il logging di debug impostando una variabile d'ambiente:

```bash
export ANTHROPIC_LOG=debug
```

### Tracciamento OpenTelemetry

Quando la tua applicazione aggiunge le sorgenti dell'SDK al suo tracer provider OpenTelemetry con `AddSource("com.anthropic.sdk.csharp*")`, 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).

### Funzionalità dell'API non documentate

L'SDK è tipizzato per un utilizzo comodo dell'API documentata. Tuttavia, supporta anche l'uso di parti dell'API non documentate o non ancora supportate.

## 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 C# supporta le seguenti piattaforme tramite pacchetti NuGet separati:

* **Agent Platform:** `Anthropic.Vertex`. Consulta [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/it/build-with-claude/claude-models-on-google-cloud/google-managed) per la configurazione del client.
* **Bedrock:** `Anthropic.Bedrock`. Usa `AnthropicBedrockMantleClient` per l'endpoint Bedrock della Messages API, oppure `AnthropicBedrockClient` (percorso `bedrock-runtime`). `AnthropicBedrockMantleClient` accetta un oggetto di configurazione `MantleAwsClientOptions` facoltativo; `AnthropicBedrockClient` accetta `AnthropicBedrockCredentialsHelper.FromEnv()` o credenziali esplicite.
* **Claude Platform on AWS:** `Anthropic.Aws`. Usa `AnthropicAwsClient`; imposta `WorkspaceId` sul client o la variabile d'ambiente `ANTHROPIC_AWS_WORKSPACE_ID` (consulta [Workspace](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws#workspaces)). Disponibile in beta.
* **Foundry:** `Anthropic.Foundry`. Usa `AnthropicFoundryClient` con `DefaultAnthropicFoundryCredentials.FromEnv()` o credenziali esplicite.

Usa `AnthropicBedrockMantleClient` per i nuovi progetti; `AnthropicBedrockClient` rimane disponibile per le applicazioni esistenti che usano l'API `InvokeModel` di Bedrock.

L'SDK C# supporta anche Claude Models on Google Cloud (Anthropic managed) tramite `AnthropicGoogleCloudClient`, dal pacchetto `Anthropic.GoogleCloud`. Questo client è in beta. Imposta `WorkspaceId` su un valore `GoogleCloudClientOptions` opzionale, 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).

## Versionamento semantico

Ogni versione major di questo SDK invia per impostazione predefinita una versione dell'API nell'intestazione `anthropic-version`, e una nuova versione major accompagna ogni nuova versione dell'API. La prima versione major che invia `2026-10-21` è la 13.0.0; consulta [Migrazione alla versione dell'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 agli elementi interni della libreria che sono tecnicamente pubblici ma non destinati o documentati per l'uso esterno.
2. 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.

## Risorse aggiuntive

* [Repository GitHub](https://github.com/anthropics/anthropic-sdk-csharp)
* [Pacchetto NuGet](https://www.nuget.org/packages/Anthropic)
* [Riferimento API](https://platform.claude.com/docs/it/api/overview)
* [Streaming dei messaggi](https://platform.claude.com/docs/it/build-with-claude/streaming)