--- title: C# SDK url: https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/sdks/csharp description: Instale e configure o SDK C# da Anthropic para aplicações .NET com integração IChatClient --- O SDK C# da Anthropic fornece acesso conveniente à Claude API a partir de aplicações escritas em C#. Para documentação de recursos da API com exemplos de código, consulte a [referência da API](https://platform.claude.com/docs/pt-BR/api/overview). Esta página aborda recursos e configurações do SDK específicos para C#. A partir da versão 10+, o pacote `Anthropic` é agora o SDK oficial da Anthropic para C#. As versões 3.X e anteriores do pacote eram usadas anteriormente para o SDK construído pela comunidade tryAGI, que foi movido para [`tryAGI.Anthropic`](https://www.nuget.org/packages/tryagi.Anthropic/). Se você precisar continuar usando o cliente anterior em seu projeto, atualize a referência do seu pacote para `tryAGI.Anthropic`. ## Instalação Instale o pacote a partir do [NuGet](https://www.nuget.org/packages/Anthropic): ```bash dotnet add package Anthropic ``` ## Requisitos Esta biblioteca requer .NET Standard 2.0 ou posterior. ## Uso ```csharp 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](https://platform.claude.com/docs/pt-BR/manage-claude/authentication). Se a sua chave de API for uma [chave pessoal ou de conta de serviço](https://platform.claude.com/docs/pt-BR/manage-claude/authentication#key-types) 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](https://platform.claude.com/docs/pt-BR/manage-claude/authentication#select-a-workspace) mostra a opção por requisição para este SDK. ## Configuração do cliente Configure o cliente usando variáveis de ambiente: ```csharp using Anthropic; // Configurado usando as variáveis de ambiente ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN e ANTHROPIC_BASE_URL AnthropicClient client = new(); ``` Ou manualmente: ```csharp 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: | Propriedade | Variável de ambiente | Obrigatório | Valor padrão | | ----------- | ---------------------- | ----------- | ----------------------------- | | `ApiKey` | `ANTHROPIC_API_KEY` | false | - | | `AuthToken` | `ANTHROPIC_AUTH_TOKEN` | false | - | | `BaseUrl` | `ANTHROPIC_BASE_URL` | true | `"https://api.anthropic.com"` | ### 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: ```csharp 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`](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/operators/with-expression) 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](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) ou [JSONL](https://jsonlines.org). 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`](https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.iasyncenumerable-1): ```csharp 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: | Status | Exceção | | ------ | ---------------------------------------- | | 400 | `AnthropicBadRequestException` | | 401 | `AnthropicUnauthorizedException` | | 403 | `AnthropicForbiddenException` | | 404 | `AnthropicNotFoundException` | | 422 | `AnthropicUnprocessableEntityException` | | 429 | `AnthropicRateLimitException` | | 5xx | `Anthropic5xxException` | | outros | `AnthropicUnexpectedStatusCodeException` | 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`: ```csharp using Anthropic; AnthropicClient client = new() { MaxRetries = 3 }; ``` Ou configure uma única chamada de método usando `WithOptions`: ```csharp 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`: ```csharp using System; using Anthropic; AnthropicClient client = new() { Timeout = TimeSpan.FromSeconds(42) }; ``` Ou configure uma única chamada de método usando `WithOptions`: ```csharp 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`](https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.iasyncenumerable-1): ```csharp 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`: ```csharp 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`: ```csharp var message = await client.Messages.Create(parameters); message.Validate(); ``` Ou configure o cliente usando a opção `ResponseValidation`: ```csharp using Anthropic; AnthropicClient client = new() { ResponseValidation = true }; ``` Ou configure uma única chamada de método usando `WithOptions`: ```csharp 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`. ```csharp 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`. ## 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`: ```csharp 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`](https://learn.microsoft.com/en-us/dotnet/api/system.io.stream), use o método [`CopyToAsync`](https://learn.microsoft.com/en-us/dotnet/api/system.io.stream.copytoasync): ```csharp 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`: ```csharp 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: ```csharp 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: ```csharp using System; var response = await client.WithRawResponse.Messages.CreateStreaming(parameters); await foreach (var item in response.Enumerate()) { Console.WriteLine(item); } ``` ### Logging Todas as mensagens de log destinam-se apenas à depuração. O formato e o conteúdo das mensagens de log podem mudar entre versões. Habilite o logging de depuração definindo uma variável de ambiente: ```bash 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](https://platform.claude.com/docs/pt-BR/manage-claude/opentelemetry/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 Para guias detalhados de configuração de plataforma com exemplos de código, consulte: * [Amazon Bedrock](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-amazon-bedrock) * [Amazon Bedrock (Opus 4.6 e anteriores)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-on-amazon-bedrock-legacy) * [Claude Platform on AWS](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws) * [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-models-on-google-cloud/google-managed) * [Microsoft Foundry](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-microsoft-foundry) Consulte também [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-models-on-google-cloud/anthropic-managed). 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)](https://platform.claude.com/docs/pt-BR/build-with-claude/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](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws#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](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution). ## 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](https://platform.claude.com/docs/pt-BR/api/migration-2026-10-21#upgrade). Este pacote geralmente segue as convenções do [SemVer](https://semver.org/spec/v2.0.0.html), 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](https://github.com/anthropics/anthropic-sdk-csharp) * [Pacote NuGet](https://www.nuget.org/packages/Anthropic) * [Referência da API](https://platform.claude.com/docs/pt-BR/api/overview) * [Streaming de mensagens](https://platform.claude.com/docs/pt-BR/build-with-claude/streaming)