C# SDK

Das Anthropic C# SDK bietet bequemen Zugriff auf die Anthropic REST 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.ClaudeOpus4_8,
};

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

Console.WriteLine(message);

Für Authentifizierungsoptionen einschließlich Workload Identity Federation siehe Authentifizierung.

Client-Konfiguration

Konfiguriere den Client mithilfe von 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 aus beiden Ansätzen.

Siehe diese Tabelle für die verfügbaren Optionen:

Konfiguration ändern

Um vorübergehend eine geänderte Client-Konfiguration zu verwenden und dabei dieselbe Verbindung und dieselben 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);

Die Verwendung eines with-Ausdrucks macht es einfach, die geänderten Optionen zu erstellen.

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

Streaming

Das SDK definiert Methoden, die Antwort-„Chunk"-Streams zurückgeben, bei denen 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 ein Streaming-Suffix in ihrem Namen, auch wenn sie keine Nicht-Streaming-Variante hat.

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.ClaudeOpus4_8,
};

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

Fehlerbehandlung

Das SDK wirft benutzerdefinierte unchecked Exception-Typen:

• AnthropicApiException: Basisklasse für API-Fehler. Siehe diese Tabelle, welche Exception-Unterklasse für welchen HTTP-Statuscode geworfen wird:

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

• AnthropicSseException: wird für Fehler 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, aber von der API unerwartet in der Antwort weggelassen wurde.

• AnthropicException: Basisklasse für alle Exceptions.

Wiederholungsversuche

Das SDK wiederholt Anfragen standardmäßig automatisch 2-mal, 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 mit der MaxRetries-Eigenschaft:

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 ab.

Um ein benutzerdefiniertes Timeout festzulegen, konfiguriere den Client mit der Timeout-Option:

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 elementweise über alle Seiten hinweg zuzugreifen.

Automatische Paginierung

Um alle Ergebnisse über alle Seiten hinweg zu durchlaufen, verwende die Paginate-Methode, 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 Items-Eigenschaft 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 mit der ResponseValidation-Option:

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 IChatClient-Interfaces aus der Microsoft.Extensions.AI.Abstractions-Bibliothek bereit. Dies ermöglicht es, AnthropicClient (und Anthropic.Services.IBetaService) mit anderen Bibliotheken zu verwenden, die mit diesen Kernabstraktionen integriert sind. Zum Beispiel können Tools aus der MCP C# SDK (ModelContextProtocol)-Bibliothek direkt mit einem AnthropicClient verwendet werden, der über IChatClient bereitgestellt wird.

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

// Verwendet 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, welche für API-Antworten verwendet werden, die nicht unbedingt geparst werden sollten, wie Nicht-JSON-Daten.

Diese Methoden geben HttpResponse zurück:

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

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

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

Console.WriteLine(response);

Um den Antwortinhalt in einer Datei oder einem beliebigen Stream zu speichern, verwende die CopyToAsync-Methode:

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

Rohe Antworten

Das SDK definiert Methoden, die Antworten in Instanzen von C#-Klassen deserialisieren. Um auf Antwort-Header, 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 RawMessage-Eigenschaft zugegriffen werden.

Für 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);

Für 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 durch Setzen einer Umgebungsvariable:

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.

Plattform-Integrationen

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

• Bedrock: Anthropic.Bedrock. Verwende AnthropicBedrockMantleClient für den Messages-API-Bedrock-Endpunkt oder AnthropicBedrockClient (bedrock-runtime-Pfad). AnthropicBedrockMantleClient nimmt ein optionales MantleAwsClientOptions-Konfigurationsobjekt entgegen; AnthropicBedrockClient akzeptiert AnthropicBedrockCredentialsHelper.FromEnv() oder explizite Anmeldedaten.
• Vertex AI: Anthropic.Vertex. Siehe Vertex AI für die Client-Einrichtung.
• Foundry: Anthropic.Foundry. Verwende AnthropicFoundryClient mit DefaultAnthropicFoundryCredentials.FromEnv() oder expliziten Anmeldedaten.
• . Verwende ; setze auf dem Client oder die Umgebungsvariable (siehe ). In der Beta verfügbar.

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, obwohl 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 Verwendung vorgesehen oder dokumentiert sind.
2. Änderungen, von denen nicht erwartet wird, dass sie die überwiegende Mehrheit der Nutzer in der Praxis betreffen.

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

Zusätzliche Ressourcen

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