CLI、SDK 和库客户端 SDK

C# SDK

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

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

C# SDK 目前处于测试版阶段。API 可能会在不同版本之间发生变化。

如需查看包含代码示例的 API 功能文档，请参阅 API 参考。本页面介绍 C# 特定的 SDK 功能和配置。

从版本 10+ 开始，Anthropic 包现在是 Anthropic 官方的 C# SDK。3.X 及以下版本的包之前用于 tryAGI 社区构建的 SDK，该 SDK 已迁移至 tryAGI.Anthropic。如果您需要在项目中继续使用之前的客户端，请将您的包引用更新为 tryAGI.Anthropic。

安装

从 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_8,
};

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

或结合使用这两种方法。

有关可用选项，请参阅下表：

属性	环境变量	必需	默认值
`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 定义了返回响应"块"流的方法，其中每个块可以在到达时立即单独处理，而无需等待完整响应。"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.ClaudeOpus4_8,
};

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-4-8")
    .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# 类的实例。

例如，应使用 MessageCreateParams 的实例调用 client.Messages.Create，它将返回一个 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); // Or any other Stream

原始响应

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

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

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

对于非流式传输响应，如果需要，您可以将响应反序列化为 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。对于 Messages-API Bedrock 端点，请使用 AnthropicBedrockMantleClient；或使用 AnthropicBedrockClient（bedrock-runtime 路径）。AnthropicBedrockMantleClient 接受一个可选的 MantleAwsClientOptions 配置对象；AnthropicBedrockClient 接受 AnthropicBedrockCredentialsHelper.FromEnv() 或显式凭据。
Vertex AI：Anthropic.Vertex。有关客户端设置，请参阅 Vertex AI。
Foundry：Anthropic.Foundry。使用 AnthropicFoundryClient 并配合 DefaultAnthropicFoundryCredentials.FromEnv() 或显式凭据。
AWS 上的 Claude Platform：Anthropic.Aws。使用 AnthropicAwsClient；在客户端上设置 WorkspaceId 或设置 ANTHROPIC_AWS_WORKSPACE_ID 环境变量（请参阅工作区）。目前处于测试版阶段。

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

语义化版本控制

尽管此包的版本号为 10+，但它目前处于测试版阶段。在测试版期间，次要版本或补丁版本中可能会出现破坏性变更。一旦该库达到稳定版本，将更严格地遵循 SemVer 约定。请通过提交 issue 分享反馈。

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

对库内部的变更，这些内容在技术上是公开的，但并非旨在供外部使用或未记录在文档中。
预计在实践中不会影响绝大多数用户的变更。

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

其他资源

Was this page helpful?

CLI、SDK 和库客户端 SDK

C# SDK

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

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

C# SDK 目前处于测试版阶段。API 可能会在不同版本之间发生变化。

如需查看包含代码示例的 API 功能文档，请参阅 API 参考。本页面介绍 C# 特定的 SDK 功能和配置。

安装

从 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_8,
};

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

或结合使用这两种方法。

有关可用选项，请参阅下表：

属性	环境变量	必需	默认值
`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 方法不会影响原始客户端或服务。

流式传输

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

这些流式传输方法返回 IAsyncEnumerable：

using System;
using Anthropic.Models.Messages;

MessageCreateParams parameters = new()
{
    MaxTokens = 1024,
    Messages =
    [
        new()
        {
            Role = Role.User,
            Content = "Hello, Claude",
        },
    ],
    Model = Model.ClaudeOpus4_8,
};

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

响应验证

如果您希望预先检查响应是否完全符合类型定义，可以调用 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 集成

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-8")
    .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# 类的实例。

例如，应使用 MessageCreateParams 的实例调用 client.Messages.Create，它将返回一个 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); // Or any other Stream

原始响应

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

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

对于非流式传输响应，如果需要，您可以将响应反序列化为 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。对于 Messages-API Bedrock 端点，请使用 AnthropicBedrockMantleClient；或使用 AnthropicBedrockClient（bedrock-runtime 路径）。AnthropicBedrockMantleClient 接受一个可选的 MantleAwsClientOptions 配置对象；AnthropicBedrockClient 接受 AnthropicBedrockCredentialsHelper.FromEnv() 或显式凭据。
Vertex AI：Anthropic.Vertex。有关客户端设置，请参阅 Vertex AI。
Foundry：Anthropic.Foundry。使用 AnthropicFoundryClient 并配合 DefaultAnthropicFoundryCredentials.FromEnv() 或显式凭据。
AWS 上的 Claude Platform：Anthropic.Aws。使用 AnthropicAwsClient；在客户端上设置 WorkspaceId 或设置 ANTHROPIC_AWS_WORKSPACE_ID 环境变量（请参阅工作区）。目前处于测试版阶段。

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

语义化版本控制

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

对库内部的变更，这些内容在技术上是公开的，但并非旨在供外部使用或未记录在文档中。
预计在实践中不会影响绝大多数用户的变更。

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

其他资源

Was this page helpful?