C# SDK

IChatClient 통합을 지원하는 .NET 애플리케이션용 Anthropic 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()
        {
            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는 응답 "청크" 스트림을 반환하는 메서드를 정의하며, 전체 응답을 기다리는 대신 각 청크가 도착하는 즉시 개별적으로 처리할 수 있습니다. "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는 사용자 정의 비검사(unchecked) 예외 타입을 발생시킵니다:

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는 바이너리 응답을 반환하는 메서드를 정의하며, 이는 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

문서화되지 않은 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 환경 변수를 설정하세요(Workspaces 참조). 베타로 제공됩니다.
Foundry: Anthropic.Foundry. DefaultAnthropicFoundryCredentials.FromEnv() 또는 명시적 자격 증명과 함께 AnthropicFoundryClient를 사용하세요.

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

시맨틱 버저닝

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

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

원활한 업그레이드 경험을 보장할 수 있도록 하위 호환성을 중요하게 다루고 있습니다.

설치

요구 사항

사용법

클라이언트 구성

구성 수정

스트리밍

오류 처리

재시도

타임아웃

페이지네이션

자동 페이지네이션

수동 페이지네이션

응답 검증

IChatClient 통합

요청 및 응답

고급 사용법

바이너리 응답

원시 응답

로깅

문서화되지 않은 API 기능

플랫폼 통합

시맨틱 버저닝

추가 리소스

설치

요구 사항

사용법

클라이언트 구성

구성 수정

스트리밍

오류 처리

재시도

타임아웃

페이지네이션

자동 페이지네이션

수동 페이지네이션

응답 검증

IChatClient 통합

요청 및 응답

고급 사용법

바이너리 응답

원시 응답

로깅

문서화되지 않은 API 기능

플랫폼 통합

시맨틱 버저닝

추가 리소스