C# SDK

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

Anthropic C# SDK 为使用 C# 编写的应用程序提供对 Anthropic REST 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.ClaudeOpus4_7,
};

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

Console.WriteLine(message);

有关认证选项（包括 Workload Identity Federation），请参阅认证。

客户端配置

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

using Anthropic;

// 使用 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_BASE_URL 环境变量配置
AnthropicClient client = new();

或手动配置：

using Anthropic;

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

或使用两种方式的组合。

请参阅下表了解可用选项：

修改配置

要临时使用修改后的客户端配置，同时复用相同的连接和线程池，请在任何客户端或服务上调用 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 定义了返回响应"分块"流的方法，每个分块在到达时即可单独处理，而无需等待完整响应。流式传输方法通常对应于 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.ClaudeOpus4_7,
};

await foreach (var message in client.Messages.CreateStreaming(parameters))
{
    Console.WriteLine(message);
}

错误处理

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

• AnthropicApiException：API 错误的基类。请参阅下表了解每个 HTTP 状态码抛出的异常子类：

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

• AnthropicSseException：在初始 HTTP 响应成功后，SSE 流式传输过程中遇到错误时抛出。

• AnthropicIOException：I/O 网络错误。

• AnthropicInvalidDataException：解释已成功解析的数据失败。例如，当访问应该必需但 API 意外从响应中省略的属性时。

• AnthropicException：所有异常的基类。

重试

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

仅重试以下错误类型：

• 连接错误（例如，由于网络连接问题）
• 408 请求超时
• 409 冲突
• 429 速率限制
• 5xx 内部错误

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 方法：

using Anthropic;
using System;

AnthropicClient client = new();

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-4-7")
    .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.Beta.Files;

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

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

Console.WriteLine(response);

要将响应内容保存到文件或任何 Stream，请使用 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); // 或任何其他 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 包支持以下平台：

• Bedrock： Anthropic.Bedrock。使用 AnthropicBedrockMantleClient 访问 Messages-API Bedrock 端点，或使用 AnthropicBedrockClient（bedrock-runtime 路径）。AnthropicBedrockMantleClient 接受可选的 MantleAwsClientOptions 配置对象；AnthropicBedrockClient 接受 AnthropicBedrockCredentialsHelper.FromEnv() 或显式凭据。
• Vertex AI： Anthropic.Vertex。有关客户端设置，请参阅 Vertex AI。
• Foundry： Anthropic.Foundry。使用 AnthropicFoundryClient 配合 DefaultAnthropicFoundryCredentials.FromEnv() 或显式凭据。
• Claude Platform on AWS： Anthropic.Aws。使用 AnthropicAwsClient；在客户端上设置 WorkspaceId 或设置 ANTHROPIC_AWS_WORKSPACE_ID 环境变量（参见工作区）。目前处于测试阶段。

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

语义化版本控制

此包通常遵循 SemVer 约定，但某些不向后兼容的更改可能作为次要版本发布：

1. 对库内部的更改，这些更改在技术上是公开的，但不打算或不对外部使用进行文档化。
2. 在实践中预计不会影响绝大多数用户的更改。

向后兼容性被认真对待，以确保你可以依赖平稳的升级体验。

附加资源

• GitHub 仓库
• NuGet 包
• API 参考
• 流式传输 Messages