SDK C#

Le SDK C# d'Anthropic offre un accès pratique à l'API Claude depuis des applications écrites en C#.

Installation

Installez le package depuis NuGet :

dotnet add package Anthropic

Prérequis

Cette bibliothèque nécessite .NET Standard 2.0 ou une version ultérieure.

Utilisation

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

Pour les options d'authentification, y compris Workload Identity Federation, consultez Authentification. Si votre clé API est une clé personnelle ou de compte de service ayant accès à plusieurs espaces de travail, définissez l'identifiant de l'espace de travail dans l'en-tête de requête anthropic-workspace-id ; Sélectionner un espace de travail présente l'option par requête pour ce SDK.

Configuration du client

Configurez le client à l'aide de variables d'environnement :

using Anthropic;

// Configuré à l'aide des variables d'environnement ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN et ANTHROPIC_BASE_URL
AnthropicClient client = new();

Ou manuellement :

using Anthropic;

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

Ou en combinant les deux approches.

Consultez ce tableau pour connaître les options disponibles :

Modification de la configuration

Pour utiliser temporairement une configuration de client modifiée, tout en réutilisant la même connexion et les mêmes pools de threads, appelez WithOptions sur n'importe quel client ou service :

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'utilisation d'une expression with facilite la construction des options modifiées.

La méthode WithOptions n'affecte pas le client ou le service d'origine.

Streaming

Le SDK définit des méthodes qui renvoient des flux de « chunks » (fragments) de réponse, où chaque fragment peut être traité individuellement dès son arrivée au lieu d'attendre la réponse complète. Les méthodes de streaming correspondent généralement à des réponses SSE ou JSONL.

Une méthode de streaming comporte toujours le suffixe Streaming dans son nom, même si elle n'a pas de variante sans streaming.

Ces méthodes de streaming renvoient un 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);
}

Gestion des erreurs

Le SDK lève des types d'exceptions personnalisées non vérifiées :

• AnthropicApiException : classe de base pour les erreurs de l'API. Consultez ce tableau pour savoir quelle sous-classe d'exception est levée pour chaque code de statut HTTP :

De plus, toutes les erreurs 4xx héritent de Anthropic4xxException.

• AnthropicSseException : levée pour les erreurs rencontrées pendant le streaming SSE après une réponse HTTP initiale réussie.

• AnthropicIOException : erreurs réseau d'E/S.

• AnthropicInvalidDataException : échec de l'interprétation de données analysées avec succès. Par exemple, lors de l'accès à une propriété censée être obligatoire, mais que l'API a omise de la réponse de manière inattendue.

• AnthropicException : classe de base pour toutes les exceptions.

Nouvelles tentatives

Le SDK effectue automatiquement 2 nouvelles tentatives par défaut, avec un court délai d'attente exponentiel (exponential backoff) entre les requêtes.

Seuls les types d'erreurs suivants font l'objet de nouvelles tentatives :

• Erreurs de connexion (par exemple, en raison d'un problème de connectivité réseau)
• 408 Request Timeout
• 409 Conflict
• 429 Rate Limit (limite de débit)
• 5xx Internal

L'API peut également indiquer explicitement au SDK de réessayer ou de ne pas réessayer une requête.

Pour définir un nombre personnalisé de nouvelles tentatives, configurez le client à l'aide de la propriété MaxRetries :

using Anthropic;

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

Ou configurez un seul appel de méthode à l'aide de WithOptions :

using System;

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

Console.WriteLine(message);

Délais d'expiration

Les requêtes expirent après 10 minutes par défaut.

Pour définir un délai d'expiration personnalisé, configurez le client à l'aide de l'option Timeout :

using System;
using Anthropic;

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

Ou configurez un seul appel de méthode à l'aide de WithOptions :

using System;

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

Console.WriteLine(message);

Pagination

Le SDK définit des méthodes qui renvoient des listes de résultats paginées. Il offre des moyens pratiques d'accéder aux résultats soit une page à la fois, soit élément par élément sur l'ensemble des pages.

Pagination automatique

Pour parcourir tous les résultats sur l'ensemble des pages, utilisez la méthode Paginate, qui récupère automatiquement des pages supplémentaires selon les besoins. La méthode renvoie un IAsyncEnumerable :

using System;

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

Pagination manuelle

Pour accéder aux éléments d'une page individuelle et demander manuellement la page suivante, utilisez la propriété Items ainsi que les méthodes HasNext et 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();
}

Validation des réponses

Dans de rares cas, l'API peut renvoyer une réponse qui ne correspond pas au type attendu. Par défaut, le SDK ne lève pas d'exception dans ce cas. Il lève AnthropicInvalidDataException uniquement si vous accédez directement à la propriété.

Si vous préférez vérifier d'emblée que la réponse est entièrement bien typée, appelez Validate :

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

Ou configurez le client à l'aide de l'option ResponseValidation :

using Anthropic;

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

Ou configurez un seul appel de méthode à l'aide de WithOptions :

using System;

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

Console.WriteLine(message);

Intégration IChatClient

Le SDK fournit une implémentation de l'interface IChatClient de la bibliothèque Microsoft.Extensions.AI.Abstractions. Cela permet d'utiliser AnthropicClient (et Anthropic.Services.IBetaService) avec d'autres bibliothèques qui s'intègrent à ces abstractions de base. Par exemple, les outils de la bibliothèque du SDK C# MCP (ModelContextProtocol) peuvent être utilisés directement avec un AnthropicClient exposé via IChatClient.

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

// Configuré à l'aide des variables d'environnement ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN et ANTHROPIC_BASE_URL
AnthropicClient client = new();

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

// Utilisation de McpClient du SDK C# 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));

Requêtes et réponses

Pour envoyer une requête à l'API Claude, construisez une instance d'une classe Params et transmettez-la à la méthode client correspondante. Lorsque la réponse est reçue, elle est désérialisée en une instance d'une classe C#.

Par exemple, client.Messages.Create doit être appelée avec une instance de MessageCreateParams, et elle renverra une instance de Task<Message>.

Utilisation avancée

Réponses binaires

Le SDK définit des méthodes qui renvoient des réponses binaires, utilisées pour les réponses de l'API qui ne doivent pas nécessairement être analysées, comme les données non JSON.

Ces méthodes renvoient HttpResponse :

using System;
using Anthropic.Models.Files;

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

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

Console.WriteLine(response);

Pour enregistrer le contenu de la réponse dans un fichier, ou dans n'importe quel Stream, utilisez la méthode CopyToAsync :

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

Réponses brutes

Le SDK définit des méthodes qui désérialisent les réponses en instances de classes C#. Pour accéder aux en-têtes de réponse, au code de statut ou au corps brut de la réponse, préfixez tout appel de méthode HTTP sur un client ou un service avec WithRawResponse :

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

Le HttpResponseMessage brut est également accessible via la propriété RawMessage.

Pour les réponses sans streaming, vous pouvez désérialiser la réponse en une instance d'une classe C# si nécessaire :

using System;
using Anthropic.Models.Messages;

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

Pour les réponses en streaming, vous pouvez désérialiser la réponse en un IAsyncEnumerable si nécessaire :

using System;

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

Journalisation

Activez la journalisation de débogage en définissant une variable d'environnement :

export ANTHROPIC_LOG=debug

Fonctionnalités non documentées de l'API

Le SDK est typé pour une utilisation pratique de l'API documentée. Cependant, il prend également en charge l'utilisation de parties de l'API non documentées ou pas encore prises en charge.

Intégrations de plateformes

Le SDK C# prend en charge les plateformes suivantes via des packages NuGet distincts :

• Agent Platform : Anthropic.Vertex. Consultez Claude sur Google Cloud pour la configuration du client.
• Bedrock : Anthropic.Bedrock. Utilisez AnthropicBedrockMantleClient pour le point de terminaison Bedrock de l'API Messages, ou AnthropicBedrockClient (chemin bedrock-runtime). AnthropicBedrockMantleClient accepte un objet de configuration MantleAwsClientOptions facultatif ; AnthropicBedrockClient accepte AnthropicBedrockCredentialsHelper.FromEnv() ou des identifiants explicites.
• Claude Platform sur AWS : Anthropic.Aws. Utilisez AnthropicAwsClient ; définissez WorkspaceId sur le client ou la variable d'environnement ANTHROPIC_AWS_WORKSPACE_ID (consultez Espaces de travail). Disponible en version bêta.
• Foundry : Anthropic.Foundry. Utilisez AnthropicFoundryClient avec DefaultAnthropicFoundryCredentials.FromEnv() ou des identifiants explicites.

Utilisez AnthropicBedrockMantleClient pour les nouveaux projets ; AnthropicBedrockClient reste disponible pour les applications existantes utilisant l'API InvokeModel de Bedrock.

Gestion sémantique des versions

Ce package suit généralement les conventions SemVer, bien que certains changements non rétrocompatibles puissent être publiés en tant que versions mineures :

1. Les modifications des éléments internes de la bibliothèque qui sont techniquement publics mais non destinés ni documentés pour un usage externe.
2. Les modifications qui ne devraient pas affecter la grande majorité des utilisateurs en pratique.

La rétrocompatibilité est prise au sérieux afin de vous garantir une expérience de mise à niveau fluide.

Ressources supplémentaires

• Dépôt GitHub
• Package NuGet
• Référence de l'API
• Streaming des messages