SDK C#

Le SDK C# d'Anthropic offre un accès pratique à l'API REST d'Anthropic 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.ClaudeOpus4_8,
};

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

Console.WriteLine(message);

Pour les options d'authentification, y compris la « Workload Identity Federation » (fédération d'identité de charge de travail), consultez Authentification.

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 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 un suffixe Streaming dans son nom, même si elle n'a pas de variante non-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.ClaudeOpus4_8,
};

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

Gestion des erreurs

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

• AnthropicApiException : classe de base pour les erreurs d'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 manière inattendue dans la réponse.

• AnthropicException : classe de base pour toutes les exceptions.

Nouvelles tentatives

Par défaut, le SDK effectue automatiquement 2 nouvelles tentatives, avec un court délai exponentiel 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
• 5xx Internal

L'API peut également indiquer explicitement au SDK de réessayer ou non 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 appel de méthode unique à 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

Par défaut, les requêtes expirent après 10 minutes.

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 appel de méthode unique à 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 paginées de résultats. 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 en amont 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 appel de méthode unique à 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-4-8")
    .AsBuilder()
    .UseFunctionInvocation()
    .Build();

// Utilisation de McpClient depuis le 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, créez une instance d'une classe Params et passez-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 d'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.Beta.Files;

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

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

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 non-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 d'API non documentées

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

Intégrations de plateformes

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

• 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.
• Vertex AI : Anthropic.Vertex. Consultez Vertex AI pour la configuration du client.
• Foundry : Anthropic.Foundry. Utilisez AnthropicFoundryClient avec DefaultAnthropicFoundryCredentials.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 (voir Espaces de travail). Disponible en version bêta.

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

Versionnage sémantique

Ce package suit généralement les conventions SemVer, bien que certains changements incompatibles avec les versions antérieures puissent être publiés en tant que versions mineures :

1. 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. 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
• Messages en streaming