C# SDK

安装并配置 Anthropic C# SDK，用于集成 IChatClient 的 .NET 应用程序

Anthropic C# SDK 为使用 C# 编写的应用程序提供了便捷访问 Claude API 的方式。

安装

从 NuGet 安装该包：

dotnet add package Anthropic

要求

此库需要 .NET Standard 2.0 或更高版本。

用法

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);
    }
}

有关包括 Workload Identity Federation（工作负载身份联合）在内的身份验证选项，请参阅身份验证。如果您的 API 密钥是可访问多个工作区的个人密钥或服务账户密钥，请在 anthropic-workspace-id 请求头中设置工作区 ID；选择工作区展示了此 SDK 的按请求设置选项。

客户端配置

使用环境变量配置客户端：

using Anthropic;

// 通过 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_BASE_URL 环境变量进行配置
AnthropicClient client = new();

或手动配置：

using Anthropic;

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

或结合使用这两种方法。

可用选项请参见下表：

属性	环境变量	必需	默认值
`ApiKey`	`ANTHROPIC_API_KEY`	false	-
`AuthToken`	`ANTHROPIC_AUTH_TOKEN`	false	-
`BaseUrl`	`ANTHROPIC_BASE_URL`	true	`"https://api.anthropic.com"`

修改配置

要临时使用修改后的客户端配置，同时复用相同的连接和线程池，请在任意客户端或服务上调用 WithOptions：

using System;

var message = await client
    .WithOptions(options =>
        options with
        {
            BaseUrl = "https://example.com",
            Timeout = TimeSpan.FromSeconds(42),
        }
    )
    .Messages.Create(parameters);

Console.WriteLine(message);

使用 with 表达式可以轻松构造修改后的选项。

WithOptions 方法不会影响原始客户端或服务。

流式传输

SDK 定义了返回响应"chunk"（块）流的方法，每个块在到达后即可单独处理，而无需等待完整响应。"Streaming"（流式传输）方法通常对应于 SSE 或 JSONL 响应。

流式传输方法的名称始终带有 Streaming 后缀，即使它没有非流式传输的变体。

这些流式传输方法返回 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);
}

错误处理

SDK 会抛出自定义的非受检异常类型：

AnthropicApiException：API 错误的基类。每个 HTTP 状态码对应抛出的异常子类请参见下表：

状态码	异常
400	`AnthropicBadRequestException`
401	`AnthropicUnauthorizedException`
403	`AnthropicForbiddenException`
404	`AnthropicNotFoundException`
422	`AnthropicUnprocessableEntityException`
429	`AnthropicRateLimitException`
5xx	`Anthropic5xxException`
其他	`AnthropicUnexpectedStatusCodeException`

此外，所有 4xx 错误都继承自 Anthropic4xxException。

AnthropicSseException：在初始 HTTP 响应成功后，SSE 流式传输过程中遇到错误时抛出。
AnthropicIOException：I/O 网络错误。
AnthropicInvalidDataException：无法解释已成功解析的数据。例如，访问一个本应为必需的属性，但 API 意外地在响应中省略了它。
AnthropicException：所有异常的基类。

重试

SDK 默认自动重试 2 次，请求之间采用短暂的指数退避。

仅以下错误类型会被重试：

连接错误（例如，由于网络连接问题）
408 Request Timeout
409 Conflict
429 Rate Limit（速率限制）
5xx Internal

API 也可能明确指示 SDK 重试或不重试某个请求。

要设置自定义重试次数，请使用 MaxRetries 属性配置客户端：

using Anthropic;

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

或使用 WithOptions 配置单次方法调用：

using System;

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

Console.WriteLine(message);

超时

请求默认在 10 分钟后超时。

要设置自定义超时，请使用 Timeout 选项配置客户端：

using System;
using Anthropic;

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

或使用 WithOptions 配置单次方法调用：

using System;

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

Console.WriteLine(message);

分页

SDK 定义了返回分页结果列表的方法。它提供了便捷的方式来访问结果，既可以一次访问一页，也可以跨所有页面逐项访问。

自动分页

要遍历所有页面的全部结果，请使用 Paginate 方法，它会根据需要自动获取更多页面。该方法返回 IAsyncEnumerable：

using System;

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

手动分页

要访问单个页面的项目并手动请求下一页，请使用 Items 属性以及 HasNext 和 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();
}

响应验证

在极少数情况下，API 可能返回与预期类型不匹配的响应。默认情况下，SDK 在这种情况下不会抛出异常。只有当您直接访问该属性时，它才会抛出 AnthropicInvalidDataException。

如果您希望预先检查响应是否完全类型正确，可以调用 Validate：

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

或使用 ResponseValidation 选项配置客户端：

using Anthropic;

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

或使用 WithOptions 配置单次方法调用：

using System;

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

Console.WriteLine(message);

IChatClient 集成

SDK 提供了 Microsoft.Extensions.AI.Abstractions 库中 IChatClient 接口的实现。这使得 AnthropicClient（以及 Anthropic.Services.IBetaService）可以与集成了这些核心抽象的其他库一起使用。例如，MCP C# SDK（ModelContextProtocol）库中的工具可以直接与通过 IChatClient 暴露的 AnthropicClient 一起使用。

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

// 通过 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_BASE_URL 环境变量进行配置
AnthropicClient client = new();

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

// 使用 MCP C# SDK 中的 McpClient
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));

请求与响应

要向 Claude API 发送请求，请构建一个 Params 类的实例并将其传递给相应的客户端方法。收到响应后，它会被反序列化为一个 C# 类的实例。

例如，client.Messages.Create 应使用 MessageCreateParams 的实例调用，并将返回 Task<Message> 的实例。

高级用法

二进制响应

SDK 定义了返回二进制响应的方法，用于不一定需要解析的 API 响应，例如非 JSON 数据。

这些方法返回 HttpResponse：

using System;
using Anthropic.Models.Files;

FileDownloadParams parameters = new() { FileID = "file_id" };

var response = await client.Files.Download(parameters);

Console.WriteLine(response);

要将响应内容保存到文件或任意 Stream，请使用 CopyToAsync 方法：

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

原始响应

SDK 定义了将响应反序列化为 C# 类实例的方法。要访问响应头、状态码或原始响应体，请在客户端或服务上的任意 HTTP 方法调用前加上 WithRawResponse：

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

原始的 HttpResponseMessage 也可以通过 RawMessage 属性访问。

对于非流式传输响应，如有需要，您可以将响应反序列化为 C# 类的实例：

using System;
using Anthropic.Models.Messages;

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

对于流式传输响应，如有需要，您可以将响应反序列化为 IAsyncEnumerable：

using System;

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

日志记录

通过设置环境变量启用调试日志：

export ANTHROPIC_LOG=debug

未文档化的 API 功能

SDK 的类型设计便于使用已文档化的 API。不过，它也支持使用 API 中未文档化或尚未支持的部分。

平台集成

C# SDK 通过独立的 NuGet 包支持以下平台：

Agent Platform： Anthropic.Vertex。客户端设置请参阅 Google Cloud 上的 Claude。
Bedrock： Anthropic.Bedrock。对于 Messages-API Bedrock 端点，请使用 AnthropicBedrockMantleClient，或使用 AnthropicBedrockClient（bedrock-runtime 路径）。AnthropicBedrockMantleClient 接受一个可选的 MantleAwsClientOptions 配置对象；AnthropicBedrockClient 接受 AnthropicBedrockCredentialsHelper.FromEnv() 或显式凭证。
Claude Platform on AWS： Anthropic.Aws。使用 AnthropicAwsClient；在客户端上设置 WorkspaceId 或设置 ANTHROPIC_AWS_WORKSPACE_ID 环境变量（请参阅工作区）。目前以 beta 形式提供。
Foundry： Anthropic.Foundry。将 AnthropicFoundryClient 与 DefaultAnthropicFoundryCredentials.FromEnv() 或显式凭证一起使用。

新项目请使用 AnthropicBedrockMantleClient；AnthropicBedrockClient 保留用于使用 Bedrock InvokeModel API 的现有应用程序。

语义化版本控制

此包总体上遵循 SemVer 约定，但某些向后不兼容的变更可能会作为次要版本发布：

对库内部的更改，这些内部在技术上是公开的，但并非为外部使用而设计或文档化。
预计在实践中不会影响绝大多数用户的更改。

我们非常重视向后兼容性，以确保您可以获得顺畅的升级体验。

安装

要求

用法

客户端配置

修改配置

流式传输

错误处理

重试

超时

分页

自动分页

手动分页

响应验证

IChatClient 集成

请求与响应

高级用法

二进制响应

原始响应

日志记录

未文档化的 API 功能

平台集成

语义化版本控制

其他资源

安装

要求

用法

客户端配置

修改配置

流式传输

错误处理

重试

超时

分页

自动分页

手动分页

响应验证

IChatClient 集成

请求与响应

高级用法

二进制响应

原始响应

日志记录

未文档化的 API 功能

平台集成

语义化版本控制

其他资源