---
title: SDK C#
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#.

<Info>
  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 cobre recursos e configurações do SDK específicos para C#.
</Info>

<Warning>
  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 criado 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 pacote para `tryAGI.Anthropic`.
</Warning>

## 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()
        {
            Role = Role.User,
            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 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) com acesso a vários workspaces, 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" (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](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()
        {
            Role = Role.User,
            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 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`:

```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 (tempo limite) 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 de páginas individuais 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 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`:

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

```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 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`:

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

<Warning>
  Todas as mensagens de log são destinadas apenas à depuração. O formato e o conteúdo das mensagens de log podem mudar entre versões.
</Warning>

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

```bash
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

<Note>
  Para guias detalhados de configuração de plataformas 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)
  * [Google Cloud](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-on-vertex-ai)
  * [Microsoft Foundry](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-microsoft-foundry)
</Note>

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

* **Agent Platform:** `Anthropic.Vertex`. Consulte [Claude no Google Cloud](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-on-vertex-ai) 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](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.

## Versionamento semântico

Este pacote geralmente segue as convenções do [SemVer](https://semver.org/spec/v2.0.0.html), 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](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)