SDK de C#

El SDK de C# de Anthropic proporciona acceso conveniente a la API REST de Anthropic desde aplicaciones escritas en C#.



Instalación

Instala el paquete desde NuGet:

dotnet add package Anthropic



Requisitos

Esta biblioteca requiere .NET Standard 2.0 o 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 conocer las opciones de autenticación, incluida Workload Identity Federation, consulta Autenticación.



Configuración del cliente

Configura el cliente usando variables de entorno:

using Anthropic;

// Se configura usando las variables de entorno ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN y ANTHROPIC_BASE_URL
AnthropicClient client = new();

O manualmente:

using Anthropic;

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

O usando una combinación de ambos enfoques.

Consulta esta tabla para ver las opciones disponibles:



Modificar la configuración

Para usar temporalmente una configuración de cliente modificada, mientras se reutilizan la misma conexión y los mismos grupos de hilos, llama a WithOptions en cualquier cliente o servicio:

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 una expresión with facilita la construcción de las opciones modificadas.

El método WithOptions no afecta al cliente o servicio original.



Streaming

El SDK define métodos que devuelven flujos de "chunks" (fragmentos) de respuesta, donde cada fragmento puede procesarse individualmente tan pronto como llega en lugar de esperar la respuesta completa. Los métodos de streaming generalmente corresponden a respuestas SSE o JSONL.

Un método de streaming siempre tiene el sufijo Streaming en su nombre, incluso si no tiene una variante sin streaming.

Estos métodos de streaming devuelven 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);
}



Manejo de errores

El SDK lanza tipos de excepciones personalizadas no verificadas:

• AnthropicApiException: Clase base para errores de la API. Consulta esta tabla para ver qué subclase de excepción se lanza para cada código de estado HTTP:

Además, todos los errores 4xx heredan de Anthropic4xxException.

• AnthropicSseException: se lanza para errores encontrados durante el streaming SSE después de una respuesta HTTP inicial exitosa.

• AnthropicIOException: errores de red de E/S.

• AnthropicInvalidDataException: Fallo al interpretar datos analizados correctamente. Por ejemplo, al acceder a una propiedad que se supone que es requerida, pero que la API omitió inesperadamente de la respuesta.

• AnthropicException: Clase base para todas las excepciones.



Reintentos

El SDK reintenta automáticamente 2 veces de forma predeterminada, con un breve retroceso exponencial entre solicitudes.

Solo se reintentan los siguientes tipos de errores:

• Errores de conexión (por ejemplo, debido a un problema de conectividad de red)
• 408 Request Timeout
• 409 Conflict
• 429 Rate Limit
• 5xx Internal

La API también puede indicar explícitamente al SDK que reintente o no reintente una solicitud.

Para establecer un número personalizado de reintentos, configura el cliente usando la propiedad MaxRetries:

using Anthropic;

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

O configura una sola llamada a método usando WithOptions:

using System;

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

Console.WriteLine(message);



Tiempos de espera

Las solicitudes expiran después de 10 minutos de forma predeterminada.

Para establecer un tiempo de espera personalizado, configura el cliente usando la opción Timeout:

using System;
using Anthropic;

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

O configura una sola llamada a método usando WithOptions:

using System;

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

Console.WriteLine(message);



Paginación

El SDK define métodos que devuelven listas paginadas de resultados. Proporciona formas convenientes de acceder a los resultados, ya sea una página a la vez o elemento por elemento a través de todas las páginas.



Paginación automática

Para iterar a través de todos los resultados en todas las páginas, usa el método Paginate, que obtiene automáticamente más páginas según sea necesario. El método devuelve un IAsyncEnumerable:

using System;

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



Paginación manual

Para acceder a los elementos de páginas individuales y solicitar manualmente la siguiente página, usa la propiedad Items, y los métodos HasNext y 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();
}



Validación de respuestas

En casos raros, la API puede devolver una respuesta que no coincide con el tipo esperado. De forma predeterminada, el SDK no lanza una excepción en este caso. Lanza AnthropicInvalidDataException solo si accedes directamente a la propiedad.

Si prefieres verificar de antemano que la respuesta está completamente bien tipada, entonces llama a Validate:

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

O configura el cliente usando la opción ResponseValidation:

using Anthropic;

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

O configura una sola llamada a método usando WithOptions:

using System;

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

Console.WriteLine(message);



Integración con IChatClient

El SDK proporciona una implementación de la interfaz IChatClient de la biblioteca Microsoft.Extensions.AI.Abstractions. Esto permite que AnthropicClient (y Anthropic.Services.IBetaService) se usen con otras bibliotecas que se integran con estas abstracciones centrales. Por ejemplo, las herramientas de la biblioteca MCP C# SDK (ModelContextProtocol) se pueden usar directamente con un AnthropicClient expuesto a través de IChatClient.

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

// Configurado usando las variables de entorno ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN y ANTHROPIC_BASE_URL
AnthropicClient client = new();

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

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



Solicitudes y respuestas

Para enviar una solicitud a la API de Claude, construye una instancia de una clase Params y pásala al método del cliente correspondiente. Cuando se recibe la respuesta, se deserializa en una instancia de una clase de C#.

Por ejemplo, client.Messages.Create debe llamarse con una instancia de MessageCreateParams, y devolverá una instancia de Task<Message>.



Uso avanzado



Respuestas binarias

El SDK define métodos que devuelven respuestas binarias, que se usan para respuestas de la API que no necesariamente deben analizarse, como datos que no son JSON.

Estos métodos devuelven 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 guardar el contenido de la respuesta en un archivo, o en cualquier Stream, usa el 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



Respuestas sin procesar

El SDK define métodos que deserializan las respuestas en instancias de clases de C#. Para acceder a los encabezados de la respuesta, el código de estado o el cuerpo de la respuesta sin procesar, antepón WithRawResponse a cualquier llamada de método HTTP en un cliente o servicio:

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

También se puede acceder al HttpResponseMessage sin procesar a través de la propiedad RawMessage.

Para respuestas sin streaming, puedes deserializar la respuesta en una instancia de una clase de C# si es necesario:

using System;
using Anthropic.Models.Messages;

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

Para respuestas con streaming, puedes deserializar la respuesta a un IAsyncEnumerable si es necesario:

using System;

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



Registro de logs

Habilita el registro de depuración estableciendo una variable de entorno:

export ANTHROPIC_LOG=debug



Funcionalidad de la API no documentada

El SDK está tipado para un uso conveniente de la API documentada. Sin embargo, también admite trabajar con partes de la API no documentadas o aún no compatibles.



Integraciones de plataformas

El SDK de C# admite las siguientes plataformas a través de paquetes NuGet separados:

• Agent Platform: Anthropic.Vertex. Consulta Claude en Google Cloud para la configuración del cliente.
• Bedrock: Anthropic.Bedrock. Usa AnthropicBedrockMantleClient para el endpoint de Bedrock de la Messages-API, o AnthropicBedrockClient (ruta bedrock-runtime). AnthropicBedrockMantleClient acepta un objeto de configuración opcional MantleAwsClientOptions; AnthropicBedrockClient acepta AnthropicBedrockCredentialsHelper.FromEnv() o credenciales explícitas.
• Claude Platform en AWS: Anthropic.Aws. Usa AnthropicAwsClient; establece WorkspaceId en el cliente o la variable de entorno ANTHROPIC_AWS_WORKSPACE_ID (consulta Workspaces). Disponible en beta.
• Foundry: Anthropic.Foundry. Usa AnthropicFoundryClient con DefaultAnthropicFoundryCredentials.FromEnv() o credenciales explícitas.

Usa AnthropicBedrockMantleClient para proyectos nuevos; AnthropicBedrockClient permanece para aplicaciones existentes que usan la API InvokeModel de Bedrock.



Versionado semántico

Este paquete generalmente sigue las convenciones de SemVer, aunque ciertos cambios incompatibles con versiones anteriores pueden publicarse como versiones menores:

1. Cambios en los componentes internos de la biblioteca que son técnicamente públicos pero no están destinados ni documentados para uso externo.
2. Cambios que no se espera que afecten a la gran mayoría de los usuarios en la práctica.

La compatibilidad con versiones anteriores se toma en serio para garantizar que puedas confiar en una experiencia de actualización fluida.



Recursos adicionales

• Repositorio de GitHub
• Paquete NuGet
• Referencia de la API
• Streaming de Messages