--- title: C# SDK url: https://platform.claude.com/docs/es/cli-sdks-libraries/sdks/csharp description: Instala y configura el SDK de C# de Anthropic para aplicaciones .NET con integración de IChatClient --- El SDK de C# de Anthropic proporciona acceso conveniente a la API de Claude desde aplicaciones escritas en C#. Para consultar la documentación de las funciones de la API con ejemplos de código, consulta la [referencia de la API](https://platform.claude.com/docs/es/api/overview). Esta página cubre las funciones y la configuración específicas del SDK de C#. A partir de la versión 10+, el paquete `Anthropic` es ahora el SDK oficial de Anthropic para C#. Las versiones del paquete 3.X e inferiores se usaban anteriormente para el SDK creado por la comunidad tryAGI, que se ha trasladado a [`tryAGI.Anthropic`](https://www.nuget.org/packages/tryagi.Anthropic/). Si necesitas seguir usando el cliente anterior en tu proyecto, actualiza la referencia de tu paquete a `tryAGI.Anthropic`. ## Instalación Instala el paquete desde [NuGet](https://www.nuget.org/packages/Anthropic): ```bash dotnet add package Anthropic ``` ## Requisitos Esta biblioteca requiere .NET Standard 2.0 o 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 conocer las opciones de autenticación, incluida "Workload Identity Federation" (federación de identidades de carga de trabajo), consulta [Autenticación](https://platform.claude.com/docs/es/manage-claude/authentication). Si tu "API key" (clave de API) es una [clave personal o de cuenta de servicio](https://platform.claude.com/docs/es/manage-claude/authentication#key-types) que no está limitada a un espacio de trabajo, establece el ID del espacio de trabajo en el encabezado de solicitud `anthropic-workspace-id`; [Seleccionar un espacio de trabajo](https://platform.claude.com/docs/es/manage-claude/authentication#select-a-workspace) muestra la opción por solicitud para este SDK. ## Configuración del cliente Configura el cliente usando variables de entorno: ```csharp using Anthropic; // Configurado mediante las variables de entorno ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN y ANTHROPIC_BASE_URL AnthropicClient client = new(); ``` O manualmente: ```csharp 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: | Propiedad | Variable de entorno | Obligatorio | Valor predeterminado | | ----------- | ---------------------- | ----------- | ----------------------------- | | `ApiKey` | `ANTHROPIC_API_KEY` | false | - | | `AuthToken` | `ANTHROPIC_AUTH_TOKEN` | false | - | | `BaseUrl` | `ANTHROPIC_BASE_URL` | true | `"https://api.anthropic.com"` | ### Modificar la configuración Para usar temporalmente una configuración de cliente modificada, reutilizando los mismos grupos de conexiones y de hilos, llama a `WithOptions` en cualquier cliente o servicio: ```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 una [expresión `with`](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/operators/with-expression) 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 en cuanto llega, en lugar de esperar la respuesta completa. Los métodos de streaming generalmente corresponden a respuestas [SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) o [JSONL](https://jsonlines.org). 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`](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); } ``` ## Manejo de errores El SDK lanza tipos de excepción personalizados no verificados: * `AnthropicApiException`: Clase base para los errores de la API. Consulta esta tabla para ver qué subclase de excepción se lanza para cada código de estado HTTP: | Estado | Excepción | | ------ | ---------------------------------------- | | 400 | `AnthropicBadRequestException` | | 401 | `AnthropicUnauthorizedException` | | 403 | `AnthropicForbiddenException` | | 404 | `AnthropicNotFoundException` | | 422 | `AnthropicUnprocessableEntityException` | | 429 | `AnthropicRateLimitException` | | 5xx | `Anthropic5xxException` | | otros | `AnthropicUnexpectedStatusCodeException` | 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 obligatoria, 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 "exponential backoff" (retroceso exponencial) entre solicitudes. Solo se reintentan los siguientes tipos de error: * 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 una solicitud. Para establecer un número personalizado de reintentos, configura el cliente usando la propiedad `MaxRetries`: ```csharp using Anthropic; AnthropicClient client = new() { MaxRetries = 3 }; ``` O configura una sola llamada a un método usando `WithOptions`: ```csharp using System; var message = await client .WithOptions(options => options with { MaxRetries = 3 } ) .Messages.Create(parameters); Console.WriteLine(message); ``` ## Tiempos de espera Las solicitudes agotan su tiempo de espera después de 10 minutos de forma predeterminada. Para establecer un tiempo de espera personalizado, configura el cliente usando la opción `Timeout`: ```csharp using System; using Anthropic; AnthropicClient client = new() { Timeout = TimeSpan.FromSeconds(42) }; ``` O configura una sola llamada a un 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); ``` ## 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`](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); } ``` ### Paginación manual Para acceder a los elementos individuales de una página y solicitar manualmente la página siguiente, usa la propiedad `Items` y los métodos `HasNext` y `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(); } ``` ## Validación de respuestas En casos poco frecuentes, 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 comprobar de antemano que la respuesta tiene tipos completamente correctos, llama a `Validate`: ```csharp var message = await client.Messages.Create(parameters); message.Validate(); ``` O configura el cliente usando la opción `ResponseValidation`: ```csharp using Anthropic; AnthropicClient client = new() { ResponseValidation = true }; ``` O configura una sola llamada a un método usando `WithOptions`: ```csharp 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 use con otras bibliotecas que se integran con estas abstracciones principales. Por ejemplo, las herramientas de la biblioteca del SDK de C# de MCP (`ModelContextProtocol`) pueden usarse directamente con un `AnthropicClient` expuesto a través de `IChatClient`. ```csharp using Anthropic; using Microsoft.Extensions.AI; using ModelContextProtocol.Client; // Configurado mediante las variables de entorno ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN y ANTHROPIC_BASE_URL AnthropicClient client = new(); IChatClient chatClient = client.AsIChatClient("claude-opus-5-5") .AsBuilder() .UseFunctionInvocation() .Build(); // Usando McpClient del SDK de MCP para C# 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, crea una instancia de una clase `Params` y pásala al método de 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`. ## 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`: ```csharp using System; using Anthropic.Models.Files; FileDownloadParams parameters = new() { FileID = "file_id" }; var response = await client.Files.Download(parameters); Console.WriteLine(response); ``` Para guardar el contenido de la respuesta en un archivo, o en cualquier [`Stream`](https://learn.microsoft.com/en-us/dotnet/api/system.io.stream), usa el 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 ``` ### Respuestas sin procesar El SDK define métodos que deserializan las respuestas en instancias de clases de C#. Para acceder a los encabezados de respuesta, al código de estado o al cuerpo de la respuesta sin procesar, antepón `WithRawResponse` a cualquier llamada a un método HTTP en un cliente o servicio: ```csharp 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: ```csharp 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 en un `IAsyncEnumerable` si es necesario: ```csharp using System; var response = await client.WithRawResponse.Messages.CreateStreaming(parameters); await foreach (var item in response.Enumerate()) { Console.WriteLine(item); } ``` ### Registro Todos los mensajes de registro están destinados únicamente a la depuración. El formato y el contenido de los mensajes de registro pueden cambiar entre versiones. Habilita el registro de depuración estableciendo una variable de entorno: ```bash export ANTHROPIC_LOG=debug ``` ### Trazado de OpenTelemetry Cuando tu aplicación agrega las fuentes del SDK a su tracer provider de OpenTelemetry con `AddSource("com.anthropic.sdk.csharp*")`, el SDK emite un span por cada solicitud que envía. Para enviar los spans a tu plataforma de observabilidad, consulta [Configura OpenTelemetry con el Claude SDK](https://platform.claude.com/docs/es/manage-claude/opentelemetry/sdk). ### Funcionalidad de la API no documentada El SDK tiene tipos para un uso conveniente de la API documentada. Sin embargo, también admite trabajar con partes de la API no documentadas o que aún no son compatibles. ## Integraciones de plataforma Para consultar guías detalladas de configuración de plataformas con ejemplos de código, consulta: * [Amazon Bedrock](https://platform.claude.com/docs/es/build-with-claude/claude-in-amazon-bedrock) * [Amazon Bedrock (Opus 4.6 y anteriores)](https://platform.claude.com/docs/es/build-with-claude/claude-on-amazon-bedrock-legacy) * [Claude Platform on AWS](https://platform.claude.com/docs/es/build-with-claude/claude-platform-on-aws) * [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/es/build-with-claude/claude-models-on-google-cloud/google-managed) * [Microsoft Foundry](https://platform.claude.com/docs/es/build-with-claude/claude-in-microsoft-foundry) Consulta también [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/es/build-with-claude/claude-models-on-google-cloud/anthropic-managed). El SDK de C# admite las siguientes plataformas a través de paquetes NuGet independientes: * **Agent Platform:** `Anthropic.Vertex`. Consulta [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/es/build-with-claude/claude-models-on-google-cloud/google-managed) 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 on AWS:** `Anthropic.Aws`. Usa `AnthropicAwsClient`; establece `WorkspaceId` en el cliente o la variable de entorno `ANTHROPIC_AWS_WORKSPACE_ID` (consulta [Workspaces](https://platform.claude.com/docs/es/build-with-claude/claude-platform-on-aws#workspaces)). Disponible en beta. * **Foundry:** `Anthropic.Foundry`. Usa `AnthropicFoundryClient` con `DefaultAnthropicFoundryCredentials.FromEnv()` o credenciales explícitas. Usa `AnthropicBedrockMantleClient` para proyectos nuevos; `AnthropicBedrockClient` se mantiene para las aplicaciones existentes que usan la API `InvokeModel` de Bedrock. El SDK de C# también es compatible con Claude Models on Google Cloud (Anthropic managed) a través de `AnthropicGoogleCloudClient`, del paquete `Anthropic.GoogleCloud`. Este cliente está en beta. Establece `WorkspaceId` en un valor `GoogleCloudClientOptions` opcional, o establece la variable de entorno `ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID`. Consulta [Resolución del proyecto, la ubicación y el workspace](https://platform.claude.com/docs/es/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution). ## Versionado semántico Cada versión principal de este SDK envía una versión de la API en el encabezado `anthropic-version` de forma predeterminada, y con cada nueva versión de la API llega una nueva versión principal. La primera versión principal que envía `2026-10-21` es la 13.0.0; consulta [Migrar a la versión de la API 2026-10-21](https://platform.claude.com/docs/es/api/migration-2026-10-21#upgrade). Este paquete generalmente sigue las convenciones de [SemVer](https://semver.org/spec/v2.0.0.html), aunque ciertos cambios incompatibles con versiones anteriores pueden publicarse como versiones menores: 1. Cambios en los componentes internos de la biblioteca que técnicamente son públicos, pero que no están destinados ni documentados para uso externo. 2. Cambios que no se espera que afecten en la práctica a la gran mayoría de los usuarios. La compatibilidad con versiones anteriores se toma en serio para garantizar que puedas contar con una experiencia de actualización sin problemas. ## Recursos adicionales * [Repositorio de GitHub](https://github.com/anthropics/anthropic-sdk-csharp) * [Paquete de NuGet](https://www.nuget.org/packages/Anthropic) * [Referencia de la API](https://platform.claude.com/docs/es/api/overview) * [Streaming de mensajes](https://platform.claude.com/docs/es/build-with-claude/streaming)