C# SDK

Anthropic C# SDK로 C# 애플리케이션에서 Claude API에 편리하게 접근해요. IChatClient 통합으로 Microsoft.Extensions.AI 생태계와 함께 쓸 수도 있어요.

출처: 문서

본문

코드 예제가 있는 API 기능 문서는 [API 레퍼런스](https://platform.claude.com/docs/en/api/overview)를 참고하세요. 이 페이지는 C# 전용 SDK 기능과 설정을 다뤄요. 버전 10 이상부터 `Anthropic` 패키지가 C#용 공식 Anthropic SDK예요. 3.X 이하 패키지 버전은 커뮤니티 빌드 tryAGI SDK에 쓰였고, 이제 [`tryAGI.Anthropic`](https://www.nuget.org/packages/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.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;

// Configured using the ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN and ANTHROPIC_BASE_URL environment variables
AnthropicClient client = new();

또는 수동으로:

using Anthropic;

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

또는 두 방식을 조합해서 써요.

사용 가능한 옵션은 이 표를 참고하세요:

속성	환경 변수	필수	기본값
`ApiKey`	`ANTHROPIC_API_KEY`	아니요	-
`AuthToken`	`ANTHROPIC_AUTH_TOKEN`	아니요	-
`BaseUrl`	`ANTHROPIC_BASE_URL`	예	`"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.ClaudeOpus5_5,
};

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가 요청을 재시도하거나 말라고 명시적으로 지시할 수도 있어요.

커스텀 재시도 횟수를 설정하려면 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;

// Configured using the ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN and ANTHROPIC_BASE_URL environment variables
AnthropicClient client = new();

IChatClient chatClient = client.AsIChatClient("claude-opus-5-5")
    .AsBuilder()
    .UseFunctionInvocation()
    .Build();

// Using McpClient from the MCP C# SDK
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.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, (bedrock-runtime 경로) AnthropicBedrockClient 사용. AnthropicBedrockMantleClient는 선택적 MantleAwsClientOptions 설정 객체를 받고, AnthropicBedrockClient는 AnthropicBedrockCredentialsHelper.FromEnv() 또는 명시적 자격 증명을 받아요.
AWS의 Claude Platform: Anthropic.Aws. AnthropicAwsClient 사용; 클라이언트의 WorkspaceId 또는 ANTHROPIC_AWS_WORKSPACE_ID 환경 변수 설정(워크스페이스 참고). 베타에서 사용 가능.
Foundry: Anthropic.Foundry. DefaultAnthropicFoundryCredentials.FromEnv() 또는 명시적 자격 증명과 함께 AnthropicFoundryClient 사용.

새 프로젝트에는 AnthropicBedrockMantleClient를, Bedrock InvokeModel API를 쓰는 기존 애플리케이션에는 AnthropicBedrockClient를 쓰세요.

시맨틱 버저닝

이 패키지는 대체로 SemVer 규칙을 따르지만, 일부 하위 호환이 깨지는 변경이 마이너 버전으로 출시될 수 있어요:

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

원활한 업그레이드 경험을 믿고 의지할 수 있도록 하위 호환성을 진지하게 지켜요.

C# SDK

C# SDK

본문

설치

요구사항

사용법

클라이언트 설정

설정 수정하기

스트리밍

오류 처리

재시도

타임아웃

페이징

자동 페이징

수동 페이징

응답 검증

IChatClient 통합

요청과 응답

고급 사용법

이진 응답

원시 응답

로깅

미문서화 API 기능

플랫폼 통합

시맨틱 버저닝

추가 자료

더 알아보기 (Learn more)