C# SDK

Anthropic C# SDK предоставляет удобный доступ к REST API Anthropic из приложений, написанных на C#.



Установка

Установите пакет из NuGet:

dotnet add package Anthropic



Требования

Эта библиотека требует .NET Standard 2.0 или более поздней версии.



Использование

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

Информацию о вариантах аутентификации, включая Workload Identity Federation, см. в разделе Аутентификация.



Конфигурация клиента

Настройте клиент с помощью переменных окружения:

using Anthropic;

// Настраивается с помощью переменных окружения ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN и ANTHROPIC_BASE_URL
AnthropicClient client = new();

Или вручную:

using Anthropic;

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

Или используя комбинацию этих двух подходов.

См. эту таблицу для доступных опций:



Изменение конфигурации

Чтобы временно использовать изменённую конфигурацию клиента, повторно используя то же соединение и пулы потоков, вызовите WithOptions на любом клиенте или сервисе:

using System;

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

Console.WriteLine(message);

Использование выражения with упрощает создание изменённых опций.

Метод WithOptions не влияет на исходный клиент или сервис.



Потоковая передача

SDK определяет методы, которые возвращают потоки «фрагментов» (chunks) ответа, где каждый фрагмент может быть обработан индивидуально сразу после его получения, вместо ожидания полного ответа. Методы потоковой передачи (streaming) обычно соответствуют ответам SSE или JSONL.

Метод потоковой передачи всегда имеет суффикс Streaming в своём имени, даже если у него нет непотокового варианта.

Эти методы потоковой передачи возвращают 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);
}



Обработка ошибок

SDK выбрасывает пользовательские непроверяемые типы исключений:

• AnthropicApiException: Базовый класс для ошибок API. См. эту таблицу, чтобы узнать, какой подкласс исключения выбрасывается для каждого кода состояния HTTP:

Кроме того, все ошибки 4xx наследуются от Anthropic4xxException.

• AnthropicSseException: выбрасывается для ошибок, возникших во время потоковой передачи SSE после успешного первоначального HTTP-ответа.

• AnthropicIOException: сетевые ошибки ввода-вывода.

• AnthropicInvalidDataException: Невозможность интерпретировать успешно разобранные данные. Например, при доступе к свойству, которое должно быть обязательным, но API неожиданно опустил его в ответе.

• AnthropicException: Базовый класс для всех исключений.



Повторные попытки

SDK по умолчанию автоматически повторяет запрос 2 раза с короткой экспоненциальной задержкой между запросами.

Повторяются только следующие типы ошибок:

• Ошибки соединения (например, из-за проблемы с сетевым подключением)
• 408 Request Timeout
• 409 Conflict
• 429 Rate Limit
• 5xx Internal

API также может явно указать SDK повторить или не повторять запрос.

Чтобы задать пользовательское количество повторных попыток, настройте клиент с помощью свойства MaxRetries:

using Anthropic;

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

Или настройте отдельный вызов метода с помощью WithOptions:

using System;

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

Console.WriteLine(message);



Тайм-ауты

По умолчанию запросы истекают по тайм-ауту через 10 минут.

Чтобы задать пользовательский тайм-аут, настройте клиент с помощью опции Timeout:

using System;
using Anthropic;

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

Или настройте отдельный вызов метода с помощью WithOptions:

using System;

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

Console.WriteLine(message);



Пагинация

SDK определяет методы, которые возвращают постраничные списки результатов. Он предоставляет удобные способы доступа к результатам либо по одной странице за раз, либо поэлементно по всем страницам.



Автоматическая пагинация

Чтобы перебрать все результаты по всем страницам, используйте метод Paginate, который автоматически загружает дополнительные страницы по мере необходимости. Метод возвращает IAsyncEnumerable:

using System;

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



Ручная пагинация

Чтобы получить доступ к элементам отдельной страницы и вручную запросить следующую страницу, используйте свойство Items и методы HasNext и 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();
}



Валидация ответов

В редких случаях API может вернуть ответ, который не соответствует ожидаемому типу. По умолчанию SDK не выбрасывает исключение в этом случае. Он выбрасывает AnthropicInvalidDataException только если вы напрямую обращаетесь к свойству.

Если вы предпочитаете заранее проверить, что ответ полностью корректно типизирован, то либо вызовите Validate:

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

Либо настройте клиент с помощью опции ResponseValidation:

using Anthropic;

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

Либо настройте отдельный вызов метода с помощью WithOptions:

using System;

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

Console.WriteLine(message);



Интеграция с IChatClient

SDK предоставляет реализацию интерфейса IChatClient из библиотеки Microsoft.Extensions.AI.Abstractions. Это позволяет использовать AnthropicClient (и Anthropic.Services.IBetaService) с другими библиотеками, которые интегрируются с этими базовыми абстракциями. Например, инструменты из библиотеки MCP C# SDK (ModelContextProtocol) могут использоваться напрямую с AnthropicClient, предоставленным через IChatClient.

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

// Настраивается с помощью переменных окружения ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN и ANTHROPIC_BASE_URL
AnthropicClient client = new();

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

// Использование McpClient из 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));



Запросы и ответы

Чтобы отправить запрос к Claude API, создайте экземпляр класса Params и передайте его соответствующему методу клиента. Когда ответ получен, он десериализуется в экземпляр класса C#.

Например, client.Messages.Create следует вызывать с экземпляром MessageCreateParams, и он вернёт экземпляр Task<Message>.



Расширенное использование



Бинарные ответы

SDK определяет методы, которые возвращают бинарные ответы, используемые для ответов API, которые не обязательно должны разбираться, например, данные не в формате JSON.

Эти методы возвращают 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);

Чтобы сохранить содержимое ответа в файл или любой Stream, используйте метод 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



Необработанные ответы

SDK определяет методы, которые десериализуют ответы в экземпляры классов C#. Чтобы получить доступ к заголовкам ответа, коду состояния или необработанному телу ответа, добавьте префикс WithRawResponse к любому вызову HTTP-метода на клиенте или сервисе:

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

Необработанный HttpResponseMessage также доступен через свойство RawMessage.

Для непотоковых ответов вы можете при необходимости десериализовать ответ в экземпляр класса C#:

using System;
using Anthropic.Models.Messages;

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

Для потоковых ответов вы можете при необходимости десериализовать ответ в IAsyncEnumerable:

using System;

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



Логирование

Включите отладочное логирование, установив переменную окружения:

export ANTHROPIC_LOG=debug



Недокументированная функциональность API

SDK типизирован для удобного использования документированного API. Однако он также поддерживает работу с недокументированными или ещё не поддерживаемыми частями API.



Интеграции с платформами

C# SDK поддерживает следующие платформы через отдельные пакеты NuGet:

• Agent Platform: Anthropic.Vertex. См. Claude на Google Cloud для настройки клиента.
• Bedrock: Anthropic.Bedrock. Используйте AnthropicBedrockMantleClient для конечной точки Bedrock с Messages API или AnthropicBedrockClient (путь bedrock-runtime). AnthropicBedrockMantleClient принимает необязательный объект конфигурации MantleAwsClientOptions; AnthropicBedrockClient принимает AnthropicBedrockCredentialsHelper.FromEnv() или явные учётные данные.
• Claude Platform на AWS: Anthropic.Aws. Используйте AnthropicAwsClient; задайте WorkspaceId на клиенте или переменную окружения ANTHROPIC_AWS_WORKSPACE_ID (см. Рабочие пространства). Доступно в бета-версии.
• Foundry: Anthropic.Foundry. Используйте AnthropicFoundryClient с DefaultAnthropicFoundryCredentials.FromEnv() или явными учётными данными.

Используйте AnthropicBedrockMantleClient для новых проектов; AnthropicBedrockClient остаётся для существующих приложений, использующих API Bedrock InvokeModel.



Семантическое версионирование

Этот пакет в целом следует соглашениям SemVer, хотя некоторые обратно несовместимые изменения могут выпускаться как минорные версии:

1. Изменения во внутренних компонентах библиотеки, которые технически являются публичными, но не предназначены и не документированы для внешнего использования.
2. Изменения, которые, как ожидается, не затронут подавляющее большинство пользователей на практике.

Обратная совместимость воспринимается серьёзно, чтобы вы могли рассчитывать на плавный процесс обновления.



Дополнительные ресурсы

• Репозиторий GitHub
• Пакет NuGet
• Справочник API
• Потоковая передача сообщений