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 定義了回傳回應「區塊」串流的方法，其中每個區塊可以在到達時立即個別處理，而不需等待完整回應。串流方法通常對應於 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# 類別的執行個體。

例如，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); // 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 套件支援以下平台：

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 慣例。請透過提交問題分享您的意見回饋。

此套件通常遵循 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 方法不會影響原始的用戶端或服務。

串流

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_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# 類別的執行個體。

例如，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); // Or any other Stream

原始回應

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。針對 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?