C# SDK

O SDK C# da Anthropic fornece acesso conveniente à Claude API a partir de aplicações escritas em C#.

Instalação

Instale o pacote a partir do NuGet:

dotnet add package Anthropic

Requisitos

Esta biblioteca requer .NET Standard 2.0 ou posterior.

Uso

using System;
using Anthropic;
using Anthropic.Models.Messages;

AnthropicClient client = new();

MessageCreateParams parameters = new()
{
    MaxTokens = 1024,
    Messages = [new UserMessageParam { Content = "Hello, Claude" }],
    Model = Model.ClaudeOpus5_5,
};

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

foreach (var block in message.Content)
{
    if (block.TryPickText(out var textBlock))
    {
        Console.WriteLine(textBlock.Text);
    }
}

Para opções de autenticação, incluindo Workload Identity Federation, consulte Autenticação. Se a sua chave de API for uma chave pessoal ou de conta de serviço que não esteja vinculada a um workspace, defina o ID do workspace no cabeçalho de requisição anthropic-workspace-id; Selecionar um workspace mostra a opção por requisição para este SDK.

Configuração do cliente

Configure o cliente usando variáveis de ambiente:

using Anthropic;

// Configurado usando as variáveis de ambiente ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN e ANTHROPIC_BASE_URL
AnthropicClient client = new();

Ou manualmente:

using Anthropic;

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

Ou usando uma combinação das duas abordagens.

Consulte esta tabela para ver as opções disponíveis:

Modificando a configuração

Para usar temporariamente uma configuração de cliente modificada, reutilizando os mesmos pools de conexão e de threads, chame WithOptions em qualquer cliente ou serviço:

using System;

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

Console.WriteLine(message);

Usar uma expressão with facilita a construção das opções modificadas.

O método WithOptions não afeta o cliente ou serviço original.

Streaming

O SDK define métodos que retornam streams de "chunks" de resposta, em que cada chunk pode ser processado individualmente assim que chega, em vez de esperar pela resposta completa. Os métodos de streaming geralmente correspondem a respostas SSE ou JSONL.

Um método de streaming sempre tem o sufixo Streaming em seu nome, mesmo que não tenha uma variante sem streaming.

Esses métodos de streaming retornam IAsyncEnumerable:

using System;
using Anthropic.Models.Messages;

MessageCreateParams parameters = new()
{
    MaxTokens = 1024,
    Messages = [new UserMessageParam { Content = "Hello, Claude" }],
    Model = Model.ClaudeOpus5_5,
};

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

Tratamento de erros

O SDK lança tipos de exceção personalizados não verificados:

• AnthropicApiException: Classe base para erros da API. Consulte esta tabela para ver qual subclasse de exceção é lançada para cada código de status HTTP:

Além disso, todos os erros 4xx herdam de Anthropic4xxException.

• AnthropicSseException: lançada para erros encontrados durante o streaming SSE após uma resposta HTTP inicial bem-sucedida.

• AnthropicIOException: Erros de rede de I/O.

• AnthropicInvalidDataException: Falha ao interpretar dados analisados com sucesso. Por exemplo, ao acessar uma propriedade que deveria ser obrigatória, mas que a API omitiu inesperadamente da resposta.

• AnthropicException: Classe base para todas as exceções.

Novas tentativas

O SDK faz automaticamente 2 novas tentativas por padrão, com um breve backoff exponencial entre as requisições.

Apenas os seguintes tipos de erro geram novas tentativas:

• Erros de conexão (por exemplo, devido a um problema de conectividade de rede)
• 408 Request Timeout
• 409 Conflict
• 429 Rate Limit
• 5xx Internal

A API também pode instruir explicitamente o SDK a tentar ou não novamente uma requisição.

Para definir um número personalizado de novas tentativas, configure o cliente usando a propriedade MaxRetries:

using Anthropic;

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

Ou configure uma única chamada de método usando WithOptions:

using System;

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

Console.WriteLine(message);

Timeouts

As requisições expiram após 10 minutos por padrão.

Para definir um timeout personalizado, configure o cliente usando a opção Timeout:

using System;
using Anthropic;

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

Ou configure uma única chamada de método usando WithOptions:

using System;

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

Console.WriteLine(message);

Paginação

O SDK define métodos que retornam listas paginadas de resultados. Ele fornece maneiras convenientes de acessar os resultados uma página por vez ou item por item em todas as páginas.

Paginação automática

Para iterar por todos os resultados em todas as páginas, use o método Paginate, que busca automaticamente mais páginas conforme necessário. O método retorna um IAsyncEnumerable:

using System;

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

Paginação manual

Para acessar itens individuais da página e solicitar manualmente a próxima página, use a propriedade Items e os métodos HasNext e 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();
}

Validação de resposta

Em casos raros, a API pode retornar uma resposta que não corresponde ao tipo esperado. Por padrão, o SDK não lança uma exceção nesse caso. Ele lança AnthropicInvalidDataException apenas se você acessar diretamente a propriedade.

Se você preferir verificar antecipadamente se a resposta está completamente bem tipada, chame Validate:

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

Ou configure o cliente usando a opção ResponseValidation:

using Anthropic;

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

Ou configure uma única chamada de método usando WithOptions:

using System;

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

Console.WriteLine(message);

Integração com IChatClient

O SDK fornece uma implementação da interface IChatClient da biblioteca Microsoft.Extensions.AI.Abstractions. Isso permite que AnthropicClient (e Anthropic.Services.IBetaService) sejam usados com outras bibliotecas que se integram a essas abstrações principais. Por exemplo, ferramentas da biblioteca MCP C# SDK (ModelContextProtocol) podem ser usadas diretamente com um AnthropicClient exposto por meio de IChatClient.

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

// Configurado usando as variáveis de ambiente ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN e ANTHROPIC_BASE_URL
AnthropicClient client = new();

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

// Usando McpClient do SDK C# do 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));

Requisições e respostas

Para enviar uma requisição à Claude API, construa uma instância de uma classe Params e passe-a para o método de cliente correspondente. Quando a resposta é recebida, ela é desserializada em uma instância de uma classe C#.

Por exemplo, client.Messages.Create deve ser chamado com uma instância de MessageCreateParams e retornará uma instância de Task<Message>.

Uso avançado

Respostas binárias

O SDK define métodos que retornam respostas binárias, que são usados para respostas da API que não precisam necessariamente ser analisadas, como dados não JSON.

Esses métodos retornam HttpResponse:

using System;
using Anthropic.Models.Files;

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

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

Console.WriteLine(response);

Para salvar o conteúdo da resposta em um arquivo, ou em qualquer Stream, use o método 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

Respostas brutas

O SDK define métodos que desserializam respostas em instâncias de classes C#. Para acessar cabeçalhos de resposta, código de status ou o corpo bruto da resposta, prefixe qualquer chamada de método HTTP em um cliente ou serviço com WithRawResponse:

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

O HttpResponseMessage bruto também pode ser acessado por meio da propriedade RawMessage.

Para respostas sem streaming, você pode desserializar a resposta em uma instância de uma classe C#, se necessário:

using System;
using Anthropic.Models.Messages;

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

Para respostas com streaming, você pode desserializar a resposta em um IAsyncEnumerable, se necessário:

using System;

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

Logging

Habilite o logging de depuração definindo uma variável de ambiente:

export ANTHROPIC_LOG=debug

Tracing do OpenTelemetry

Quando a sua aplicação adiciona as sources do SDK ao tracer provider do OpenTelemetry com AddSource("com.anthropic.sdk.csharp*"), o SDK emite um span para cada requisição que envia. Para enviar os spans para a sua plataforma de observabilidade, consulte Configurar o OpenTelemetry com o Claude SDK.

Funcionalidades não documentadas da API

O SDK é tipado para uso conveniente da API documentada. No entanto, ele também oferece suporte ao trabalho com partes da API não documentadas ou ainda não suportadas.

Integrações de plataforma

O SDK C# oferece suporte às seguintes plataformas por meio de pacotes NuGet separados:

• Agent Platform: Anthropic.Vertex. Consulte Claude Models on Google Cloud (Google managed) para a configuração do cliente.
• Bedrock: Anthropic.Bedrock. Use AnthropicBedrockMantleClient para o endpoint Bedrock da Messages API, ou AnthropicBedrockClient (caminho bedrock-runtime). AnthropicBedrockMantleClient aceita um objeto de configuração opcional MantleAwsClientOptions; AnthropicBedrockClient aceita AnthropicBedrockCredentialsHelper.FromEnv() ou credenciais explícitas.
• Claude Platform on AWS: Anthropic.Aws. Use AnthropicAwsClient; defina WorkspaceId no cliente ou a variável de ambiente ANTHROPIC_AWS_WORKSPACE_ID (consulte Workspaces). Disponível em beta.
• Foundry: Anthropic.Foundry. Use AnthropicFoundryClient com DefaultAnthropicFoundryCredentials.FromEnv() ou credenciais explícitas.

Use AnthropicBedrockMantleClient para novos projetos; AnthropicBedrockClient permanece para aplicações existentes que usam a API InvokeModel do Bedrock.

O SDK C# também oferece suporte a Claude Models on Google Cloud (Anthropic managed) por meio de AnthropicGoogleCloudClient, do pacote Anthropic.GoogleCloud. Este cliente está em beta. Defina WorkspaceId em um valor GoogleCloudClientOptions opcional, ou defina a variável de ambiente ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID. Consulte Resolução de projeto, localização e workspace.

Versionamento semântico

Cada versão principal deste SDK envia uma versão da API no cabeçalho anthropic-version por padrão, e uma nova versão principal acompanha cada nova versão da API. A primeira versão principal que envia 2026-10-21 é a 13.0.0; consulte Migrando para a versão da API 2026-10-21.

Este pacote geralmente segue as convenções do SemVer, embora certas alterações incompatíveis com versões anteriores possam ser lançadas como versões secundárias:

1. Alterações em componentes internos da biblioteca que são tecnicamente públicos, mas não destinados ou documentados para uso externo.
2. Alterações que não se espera que afetem a grande maioria dos usuários na prática.

A compatibilidade com versões anteriores é levada a sério para garantir que você possa contar com uma experiência de atualização tranquila.

Recursos adicionais

• Repositório no GitHub
• Pacote NuGet
• Referência da API
• Streaming de mensagens