C# SDK

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

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

또는 두 가지 방법을 조합하여 사용할 수도 있습니다.

사용 가능한 옵션은 다음 표를 참조하세요:

구성 수정

동일한 연결 및 스레드 풀을 재사용하면서 수정된 클라이언트 구성을 일시적으로 사용하려면, 클라이언트나 서비스에서 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"(청크) 스트림을 반환하는 메서드를 정의하며, 각 청크는 전체 응답을 기다리지 않고 도착하는 즉시 개별적으로 처리할 수 있습니다. 스트리밍 메서드는 일반적으로 SSE 또는 JSONL 응답에 대응합니다.

스트리밍 메서드는 비스트리밍 버전이 없더라도 항상 이름에 Streaming 접미사가 붙습니다.

이러한 스트리밍 메서드는 IAsyncEnumerable을 반환합니다:

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

오류 처리

SDK는 사용자 정의 unchecked 예외 유형을 발생시킵니다:

• AnthropicApiException: API 오류의 기본 클래스입니다. 각 HTTP 상태 코드에 대해 어떤 예외 하위 클래스가 발생하는지는 다음 표를 참조하세요:

또한 모든 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-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는 바이너리 응답을 반환하는 메서드를 정의하며, 이는 JSON이 아닌 데이터처럼 반드시 파싱할 필요가 없는 API 응답에 사용됩니다.

이러한 메서드는 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

OpenTelemetry 추적

애플리케이션이 AddSource("com.anthropic.sdk.csharp*")를 사용해 OpenTelemetry 트레이서 프로바이더에 SDK의 소스를 추가하면 SDK는 전송하는 각 요청에 대해 스팬을 내보냅니다. 스팬을 관측성 플랫폼으로 전송하려면 Claude SDK에서 OpenTelemetry 설정하기를 참조하세요.

문서화되지 않은 API 기능

SDK는 문서화된 API를 편리하게 사용할 수 있도록 타입이 지정되어 있습니다. 하지만 문서화되지 않았거나 아직 지원되지 않는 API 부분을 사용하는 것도 지원합니다.

플랫폼 통합

C# SDK는 별도의 NuGet 패키지를 통해 다음 플랫폼을 지원합니다:

• Agent Platform: Anthropic.Vertex. 클라이언트 설정은 Claude Models on Google Cloud (Google managed)를 참조하세요.
• Bedrock: Anthropic.Bedrock. Messages API Bedrock 엔드포인트에는 AnthropicBedrockMantleClient를 사용하고, bedrock-runtime 경로에는 AnthropicBedrockClient를 사용하세요. AnthropicBedrockMantleClient는 선택적 MantleAwsClientOptions 구성 객체를 받으며, AnthropicBedrockClient는 AnthropicBedrockCredentialsHelper.FromEnv() 또는 명시적 자격 증명을 받습니다.
• Claude Platform on AWS: Anthropic.Aws. AnthropicAwsClient를 사용하고, 클라이언트에 WorkspaceId를 설정하거나 ANTHROPIC_AWS_WORKSPACE_ID 환경 변수를 설정하세요(워크스페이스 참조). 베타로 제공됩니다.
• Foundry: Anthropic.Foundry. DefaultAnthropicFoundryCredentials.FromEnv() 또는 명시적 자격 증명과 함께 AnthropicFoundryClient를 사용하세요.

새 프로젝트에는 AnthropicBedrockMantleClient를 사용하세요. AnthropicBedrockClient는 Bedrock InvokeModel API를 사용하는 기존 애플리케이션을 위해 유지됩니다.

C# SDK는 Anthropic.GoogleCloud 패키지의 AnthropicGoogleCloudClient를 통해 Claude Models on Google Cloud (Anthropic managed)도 지원합니다. 이 클라이언트는 베타 상태입니다. 선택적 GoogleCloudClientOptions 값에 WorkspaceId를 설정하거나 ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID 환경 변수를 설정하세요. 프로젝트, 위치 및 워크스페이스 확인을 참조하세요.

시맨틱 버전 관리

이 SDK의 각 메이저 버전은 기본적으로 anthropic-version 헤더에 하나의 API 버전을 전송하며, 새로운 API 버전마다 새로운 메이저 버전이 함께 출시됩니다. 2026-10-21을 전송하는 첫 번째 메이저 버전은 13.0.0입니다. API 버전 2026-10-21로 마이그레이션을 참조하세요.

이 패키지는 일반적으로 SemVer 규칙을 따르지만, 일부 하위 호환되지 않는 변경 사항이 마이너 버전으로 릴리스될 수 있습니다:

1. 기술적으로는 공개되어 있지만 외부 사용을 의도하거나 문서화하지 않은 라이브러리 내부 변경 사항.
2. 실제로 대다수 사용자에게 영향을 미치지 않을 것으로 예상되는 변경 사항.

원활한 업그레이드 경험을 신뢰할 수 있도록 하위 호환성을 중요하게 고려합니다.

추가 리소스

• GitHub 저장소
• NuGet 패키지
• API 레퍼런스
• 메시지 스트리밍