C# SDK

Das Anthropic C# SDK bietet bequemen Zugriff auf die Claude API aus Anwendungen, die in C# geschrieben sind.

Installation

Installiere das Paket von NuGet:

dotnet add package Anthropic

Anforderungen

Diese Bibliothek erfordert .NET Standard 2.0 oder höher.

Verwendung

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

Authentifizierungsoptionen einschließlich Workload Identity Federation findest du unter Authentifizierung. Wenn dein API-Key ein persönlicher Key oder ein Service-Account-Key mit Zugriff auf mehrere Workspaces ist, setze die Workspace-ID im Request-Header anthropic-workspace-id; Einen Workspace auswählen zeigt die Option pro Anfrage für dieses SDK.

Client-Konfiguration

Konfiguriere den Client über Umgebungsvariablen:

using Anthropic;

// Konfiguriert über die Umgebungsvariablen ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN und ANTHROPIC_BASE_URL
AnthropicClient client = new();

Oder manuell:

using Anthropic;

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

Oder mit einer Kombination beider Ansätze.

In dieser Tabelle findest du die verfügbaren Optionen:

Konfiguration ändern

Um vorübergehend eine geänderte Client-Konfiguration zu verwenden und dabei dieselben Verbindungs- und Thread-Pools wiederzuverwenden, rufe WithOptions auf einem beliebigen Client oder Service auf:

using System;

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

Console.WriteLine(message);

Mit einem with-Ausdruck lassen sich die geänderten Optionen einfach erstellen.

Die Methode WithOptions wirkt sich nicht auf den ursprünglichen Client oder Service aus.

Streaming

Das SDK definiert Methoden, die Streams von Antwort-„Chunks“ zurückgeben, wobei jeder Chunk einzeln verarbeitet werden kann, sobald er eintrifft, anstatt auf die vollständige Antwort zu warten. Streaming-Methoden entsprechen im Allgemeinen SSE- oder JSONL-Antworten.

Eine Streaming-Methode hat immer das Suffix Streaming im Namen, auch wenn es keine Nicht-Streaming-Variante gibt.

Diese Streaming-Methoden geben IAsyncEnumerable zurück:

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

Fehlerbehandlung

Das SDK wirft benutzerdefinierte ungeprüfte Exception-Typen:

• AnthropicApiException: Basisklasse für API-Fehler. In dieser Tabelle siehst du, welche Exception-Unterklasse für welchen HTTP-Statuscode geworfen wird:

Zusätzlich erben alle 4xx-Fehler von Anthropic4xxException.

• AnthropicSseException: wird bei Fehlern geworfen, die während des SSE-Streamings nach einer erfolgreichen initialen HTTP-Antwort auftreten.

• AnthropicIOException: I/O-Netzwerkfehler.

• AnthropicInvalidDataException: Fehler beim Interpretieren erfolgreich geparster Daten. Zum Beispiel beim Zugriff auf eine Eigenschaft, die eigentlich erforderlich sein sollte, die die API aber unerwartet in der Antwort weggelassen hat.

• AnthropicException: Basisklasse für alle Exceptions.

Wiederholungsversuche

Das SDK führt standardmäßig automatisch 2 Wiederholungsversuche durch, mit einem kurzen exponentiellen Backoff zwischen den Anfragen.

Nur die folgenden Fehlertypen werden wiederholt:

• Verbindungsfehler (zum Beispiel aufgrund eines Netzwerkverbindungsproblems)
• 408 Request Timeout
• 409 Conflict
• 429 Rate Limit
• 5xx Internal

Die API kann das SDK auch explizit anweisen, eine Anfrage zu wiederholen oder nicht zu wiederholen.

Um eine benutzerdefinierte Anzahl von Wiederholungsversuchen festzulegen, konfiguriere den Client über die Eigenschaft MaxRetries:

using Anthropic;

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

Oder konfiguriere einen einzelnen Methodenaufruf mit WithOptions:

using System;

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

Console.WriteLine(message);

Timeouts

Anfragen laufen standardmäßig nach 10 Minuten in einen Timeout.

Um einen benutzerdefinierten Timeout festzulegen, konfiguriere den Client über die Option Timeout:

using System;
using Anthropic;

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

Oder konfiguriere einen einzelnen Methodenaufruf mit WithOptions:

using System;

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

Console.WriteLine(message);

Paginierung

Das SDK definiert Methoden, die paginierte Ergebnislisten zurückgeben. Es bietet bequeme Möglichkeiten, auf die Ergebnisse entweder seitenweise oder Element für Element über alle Seiten hinweg zuzugreifen.

Automatische Paginierung

Um alle Ergebnisse über alle Seiten hinweg zu durchlaufen, verwende die Methode Paginate, die bei Bedarf automatisch weitere Seiten abruft. Die Methode gibt ein IAsyncEnumerable zurück:

using System;

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

Manuelle Paginierung

Um auf einzelne Seitenelemente zuzugreifen und die nächste Seite manuell anzufordern, verwende die Eigenschaft Items sowie die Methoden HasNext und 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();
}

Antwortvalidierung

In seltenen Fällen kann die API eine Antwort zurückgeben, die nicht dem erwarteten Typ entspricht. Standardmäßig wirft das SDK in diesem Fall keine Exception. Es wirft AnthropicInvalidDataException nur, wenn du direkt auf die Eigenschaft zugreifst.

Wenn du lieber vorab prüfen möchtest, ob die Antwort vollständig korrekt typisiert ist, rufe entweder Validate auf:

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

Oder konfiguriere den Client über die Option ResponseValidation:

using Anthropic;

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

Oder konfiguriere einen einzelnen Methodenaufruf mit WithOptions:

using System;

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

Console.WriteLine(message);

IChatClient-Integration

Das SDK stellt eine Implementierung des Interfaces IChatClient aus der Bibliothek Microsoft.Extensions.AI.Abstractions bereit. Dadurch können AnthropicClient (und Anthropic.Services.IBetaService) mit anderen Bibliotheken verwendet werden, die sich in diese Kernabstraktionen integrieren. Zum Beispiel können Tools aus der MCP-C#-SDK-Bibliothek (ModelContextProtocol) direkt mit einem über IChatClient bereitgestellten AnthropicClient verwendet werden.

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

// Konfiguriert über die Umgebungsvariablen ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN und ANTHROPIC_BASE_URL
AnthropicClient client = new();

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

// Verwendung von McpClient aus dem MCP C# SDK
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));

Anfragen und Antworten

Um eine Anfrage an die Claude API zu senden, erstelle eine Instanz einer Params-Klasse und übergib sie an die entsprechende Client-Methode. Wenn die Antwort empfangen wird, wird sie in eine Instanz einer C#-Klasse deserialisiert.

Zum Beispiel sollte client.Messages.Create mit einer Instanz von MessageCreateParams aufgerufen werden und gibt eine Instanz von Task<Message> zurück.

Erweiterte Verwendung

Binäre Antworten

Das SDK definiert Methoden, die binäre Antworten zurückgeben. Diese werden für API-Antworten verwendet, die nicht unbedingt geparst werden sollten, wie etwa Nicht-JSON-Daten.

Diese Methoden geben HttpResponse zurück:

using System;
using Anthropic.Models.Files;

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

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

Console.WriteLine(response);

Um den Antwortinhalt in einer Datei oder einem beliebigen Stream zu speichern, verwende die Methode 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

Rohe Antworten

Das SDK definiert Methoden, die Antworten in Instanzen von C#-Klassen deserialisieren. Um auf Antwort-Header, den Statuscode oder den rohen Antwort-Body zuzugreifen, stelle jedem HTTP-Methodenaufruf auf einem Client oder Service WithRawResponse voran:

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

Auf die rohe HttpResponseMessage kann auch über die Eigenschaft RawMessage zugegriffen werden.

Bei Nicht-Streaming-Antworten kannst du die Antwort bei Bedarf in eine Instanz einer C#-Klasse deserialisieren:

using System;
using Anthropic.Models.Messages;

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

Bei Streaming-Antworten kannst du die Antwort bei Bedarf in ein IAsyncEnumerable deserialisieren:

using System;

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

Logging

Aktiviere Debug-Logging, indem du eine Umgebungsvariable setzt:

export ANTHROPIC_LOG=debug

Undokumentierte API-Funktionalität

Das SDK ist für die bequeme Nutzung der dokumentierten API typisiert. Es unterstützt jedoch auch die Arbeit mit undokumentierten oder noch nicht unterstützten Teilen der API.

Plattformintegrationen

Das C# SDK unterstützt die folgenden Plattformen über separate NuGet-Pakete:

• Agent Platform: Anthropic.Vertex. Siehe Claude auf Google Cloud für die Client-Einrichtung.
• Bedrock: Anthropic.Bedrock. Verwende AnthropicBedrockMantleClient für den Messages-API-Bedrock-Endpunkt oder AnthropicBedrockClient (bedrock-runtime-Pfad). AnthropicBedrockMantleClient akzeptiert ein optionales MantleAwsClientOptions-Konfigurationsobjekt; AnthropicBedrockClient akzeptiert AnthropicBedrockCredentialsHelper.FromEnv() oder explizite Anmeldedaten.
• Claude Platform on AWS: Anthropic.Aws. Verwende AnthropicAwsClient; setze WorkspaceId auf dem Client oder die Umgebungsvariable ANTHROPIC_AWS_WORKSPACE_ID (siehe Workspaces). In der Beta-Phase verfügbar.
• Foundry: Anthropic.Foundry. Verwende AnthropicFoundryClient mit DefaultAnthropicFoundryCredentials.FromEnv() oder expliziten Anmeldedaten.

Verwende AnthropicBedrockMantleClient für neue Projekte; AnthropicBedrockClient bleibt für bestehende Anwendungen erhalten, die die Bedrock-InvokeModel-API verwenden.

Semantische Versionierung

Dieses Paket folgt im Allgemeinen den SemVer-Konventionen, wobei bestimmte rückwärtsinkompatible Änderungen als Minor-Versionen veröffentlicht werden können:

1. Änderungen an Bibliotheksinterna, die technisch öffentlich sind, aber nicht für die externe Nutzung vorgesehen oder dokumentiert sind.
2. Änderungen, von denen nicht erwartet wird, dass sie in der Praxis die überwiegende Mehrheit der Nutzer betreffen.

Rückwärtskompatibilität wird ernst genommen, damit du dich auf ein reibungsloses Upgrade-Erlebnis verlassen kannst.

Zusätzliche Ressourcen

• GitHub-Repository
• NuGet-Paket
• API-Referenz
• Streaming von Nachrichten