SDK C#

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

Para opções de autenticação, incluindo Workload Identity Federation, consulte Autenticação. Se sua chave de API for uma chave pessoal ou de conta de serviço com acesso a vários workspaces, 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" (fragmentos) de resposta, onde cada chunk pode ser processado individualmente assim que chega, em vez de aguardar a 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()
        {
            Role = Role.User,
            Content = "Hello, Claude",
        },
    ],
    Model = Model.ClaudeOpus5,
};

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 E/S.

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

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

Novas tentativas

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

Apenas os seguintes tipos de erro são tentados novamente:

• 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 novamente ou não 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 (tempo limite) 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 de páginas individuais 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 respostas

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 que 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) seja usado com outras bibliotecas que se integram a essas abstrações principais. Por exemplo, ferramentas da biblioteca do SDK C# do MCP (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")
    .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 correspondente do cliente. 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 usadas para respostas da API que não devem 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

Funcionalidade não documentada 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 com plataformas

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

• Agent Platform: Anthropic.Vertex. Consulte Claude no Google Cloud para a configuração do cliente.
• Bedrock: Anthropic.Bedrock. Use AnthropicBedrockMantleClient para o endpoint Bedrock da Messages API, ou AnthropicBedrockClient (caminho bedrock-runtime). AnthropicBedrockMantleClient recebe 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.

Versionamento semântico

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

1. Mudanças em partes internas da biblioteca que são tecnicamente públicas, mas não destinadas ou documentadas para uso externo.
2. Mudanças que não devem impactar 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