SDK C#

O SDK C# da Anthropic fornece acesso conveniente à API REST da Anthropic 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.ClaudeOpus4_8,
};

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

Console.WriteLine(message);

Para opções de autenticação, incluindo Workload Identity Federation, consulte Autenticação.

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 as opções disponíveis:

Modificando a configuração

Para usar temporariamente uma configuração de cliente modificada, reutilizando a mesma conexão e pools 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" (pedaços) de resposta, onde cada chunk pode ser processado individualmente assim que chega, em vez de esperar pela resposta completa. Métodos de streaming geralmente correspondem a respostas SSE ou JSONL.

Um método de streaming sempre tem um 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.ClaudeOpus4_8,
};

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

Tratamento de erros

O SDK lança tipos de exceção não verificadas personalizadas:

• AnthropicApiException: Classe base para erros de API. Consulte esta tabela para saber 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 a API inesperadamente a omitiu da resposta.

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

Novas tentativas

O SDK tenta novamente 2 vezes automaticamente por padrão, com um curto backoff exponencial entre as requisições.

Apenas os seguintes tipos de erro são repetidos:

• 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 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 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) seja usado com outras bibliotecas que se integram a essas abstrações principais. Por exemplo, ferramentas no SDK C# do MCP (biblioteca ModelContextProtocol) podem ser usadas diretamente com um AnthropicClient exposto através 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-4-8")
    .AsBuilder()
    .UseFunctionInvocation()
    .Build();

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

Requisições e respostas

Para enviar uma requisição à API do Claude, 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 usadas para respostas de API que não devem necessariamente ser analisadas, como dados não JSON.

Esses métodos retornam 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);

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

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 através 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 de API não documentada

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

Integrações de plataforma

O SDK C# suporta as seguintes plataformas através de pacotes NuGet separados:

• Bedrock: Anthropic.Bedrock. Use AnthropicBedrockMantleClient para o endpoint Bedrock da API de Messages, ou AnthropicBedrockClient (caminho bedrock-runtime). AnthropicBedrockMantleClient recebe um objeto de configuração opcional MantleAwsClientOptions; AnthropicBedrockClient aceita AnthropicBedrockCredentialsHelper.FromEnv() ou credenciais explícitas.
• Vertex AI: Anthropic.Vertex. Consulte Vertex AI para configuração do cliente.
• Foundry: Anthropic.Foundry. Use AnthropicFoundryClient com DefaultAnthropicFoundryCredentials.FromEnv() ou credenciais explícitas.
• Claude Platform na 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.

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 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 GitHub
• Pacote NuGet
• Referência da API
• Streaming de Mensagens