SDK C#

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



Installazione

Installa il pacchetto da NuGet:

dotnet add package Anthropic



Requisiti

Questa libreria richiede .NET Standard 2.0 o successivo.



Utilizzo

using System;
using Anthropic;
using Anthropic.Models.Messages;

AnthropicClient client = new();

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

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.



Configurazione del client

Configura il client utilizzando le variabili d'ambiente:

using Anthropic;

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

Oppure manualmente:

using Anthropic;

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

Oppure utilizzando una combinazione dei due approcci.

Consulta questa tabella per le opzioni disponibili:



Modificare la configurazione

Per utilizzare temporaneamente una configurazione del client modificata, riutilizzando la stessa connessione e gli stessi thread pool, chiama WithOptions su qualsiasi client o servizio:

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'utilizzo di un'espressione with rende facile costruire le opzioni modificate.

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



Streaming

L'SDK definisce metodi che restituiscono flussi di "chunk" di risposta, dove ogni chunk può essere elaborato individualmente non appena arriva invece di attendere la risposta completa. I metodi di streaming corrispondono generalmente a risposte SSE o JSONL.

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

Questi metodi di streaming restituiscono IAsyncEnumerable:

using System;
using Anthropic.Models.Messages;

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

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



Gestione degli errori

L'SDK genera tipi di eccezioni personalizzate non controllate:

• AnthropicApiException: Classe base per gli errori API. Consulta questa tabella per sapere quale sottoclasse di eccezione viene generata per ciascun codice di stato HTTP:

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 I/O.

• AnthropicInvalidDataException: Impossibilità di interpretare dati analizzati con successo. 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

L'SDK riprova automaticamente 2 volte per impostazione predefinita, con un breve backoff esponenziale tra le richieste.

Solo i seguenti tipi di errore vengono ritentati:

• 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 istruire esplicitamente l'SDK a ritentare o non ritentare una richiesta.

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

using Anthropic;

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

Oppure configura una singola chiamata di metodo utilizzando WithOptions:

using System;

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

Console.WriteLine(message);



Timeout

Le richieste vanno in timeout dopo 10 minuti per impostazione predefinita.

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

using System;
using Anthropic;

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

Oppure configura una singola chiamata di metodo utilizzando WithOptions:

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. Fornisce modi comodi per accedere ai risultati una pagina alla volta o elemento per elemento attraverso tutte le pagine.



Paginazione automatica

Per iterare attraverso tutti i risultati di tutte le pagine, usa il metodo Paginate, che recupera automaticamente più pagine secondo necessità. Il metodo restituisce un IAsyncEnumerable:

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:

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 potrebbe restituire una risposta che non corrisponde al tipo previsto. Per impostazione predefinita, l'SDK non genera un'eccezione in questo caso. Genera AnthropicInvalidDataException solo se accedi direttamente alla proprietà.

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

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

Oppure configura il client utilizzando l'opzione ResponseValidation:

using Anthropic;

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

Oppure configura una singola chiamata di metodo utilizzando WithOptions:

using System;

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

Console.WriteLine(message);



Integrazione IChatClient

L'SDK fornisce un'implementazione dell'interfaccia IChatClient dalla libreria Microsoft.Extensions.AI.Abstractions. Questo consente a AnthropicClient (e Anthropic.Services.IBetaService) di essere utilizzato con altre librerie che si integrano con queste astrazioni di base. Ad esempio, gli strumenti nella libreria MCP C# SDK (ModelContextProtocol) possono essere utilizzati direttamente con un AnthropicClient esposto tramite IChatClient.

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")
    .AsBuilder()
    .UseFunctionInvocation()
    .Build();

// Utilizzo 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 all'API di Claude, costruisci un'istanza di una classe Params e passala al metodo client corrispondente. Quando la risposta viene ricevuta, viene deserializzata in un'istanza di una classe C#.

Ad esempio, client.Messages.Create dovrebbe 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, che vengono utilizzate per risposte API che non devono necessariamente essere analizzate, come dati non JSON.

Questi metodi restituiscono HttpResponse:

using System;
using Anthropic.Models.Beta.Files;

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

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

Console.WriteLine(response);

Per salvare il contenuto della risposta in un file, o in qualsiasi Stream, usa il metodo CopyToAsync:

using System.IO;

using var response = await client.Beta.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 raw

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

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

Il HttpResponseMessage raw può anche essere accessibile tramite la proprietà RawMessage.

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

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:

using System;

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



Logging

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

export ANTHROPIC_LOG=debug



Funzionalità API non documentate

L'SDK è tipizzato per un utilizzo comodo dell'API documentata. Tuttavia, supporta anche il lavoro con parti dell'API non documentate o non ancora supportate.



Integrazioni con le piattaforme

L'SDK C# supporta le seguenti piattaforme tramite pacchetti NuGet separati:

• Agent Platform: Anthropic.Vertex. Consulta Claude su Google Cloud per la configurazione del client.
• Bedrock: Anthropic.Bedrock. Usa AnthropicBedrockMantleClient per l'endpoint Bedrock dell'API Messages, oppure AnthropicBedrockClient (percorso bedrock-runtime). AnthropicBedrockMantleClient accetta un oggetto di configurazione opzionale MantleAwsClientOptions; AnthropicBedrockClient accetta AnthropicBedrockCredentialsHelper.FromEnv() o credenziali esplicite.
• Claude Platform su AWS: Anthropic.Aws. Usa AnthropicAwsClient; imposta WorkspaceId sul client o la variabile d'ambiente ANTHROPIC_AWS_WORKSPACE_ID (consulta Workspaces). Disponibile in beta.
• Foundry: Anthropic.Foundry. Usa AnthropicFoundryClient con DefaultAnthropicFoundryCredentials.FromEnv() o credenziali esplicite.

Usa AnthropicBedrockMantleClient per i nuovi progetti; AnthropicBedrockClient 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 incompatibili con le versioni precedenti potrebbero essere rilasciate come versioni minor:

1. Modifiche agli interni della libreria che sono tecnicamente pubblici ma non destinati o documentati per l'uso esterno.
2. Modifiche che non dovrebbero avere impatto sulla stragrande maggioranza degli utenti nella pratica.

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



Risorse aggiuntive

• Repository GitHub
• Pacchetto NuGet
• Riferimento API
• Streaming dei messaggi