---
title: C# SDK
url: https://platform.claude.com/docs/ko/cli-sdks-libraries/sdks/csharp
description: IChatClient 통합을 지원하는 .NET 애플리케이션용 Anthropic C# SDK를 설치하고 구성합니다
---

Anthropic C# SDK는 C#으로 작성된 애플리케이션에서 Claude API에 편리하게 액세스할 수 있도록 해줍니다.

<Info>
  코드 예제가 포함된 API 기능 문서는 [API 레퍼런스](https://platform.claude.com/docs/ko/api/overview)를 참조하세요. 이 페이지는 C# 전용 SDK 기능 및 구성을 다룹니다.
</Info>

<Warning>
  버전 10 이상부터 `Anthropic` 패키지는 이제 공식 Anthropic C# SDK입니다. 패키지 버전 3.X 이하는 이전에 tryAGI 커뮤니티에서 제작한 SDK에 사용되었으며, 해당 SDK는 [`tryAGI.Anthropic`](https://www.nuget.org/packages/tryagi.Anthropic/)으로 이전되었습니다. 프로젝트에서 이전 클라이언트를 계속 사용해야 하는 경우 패키지 참조를 `tryAGI.Anthropic`으로 업데이트하세요.
</Warning>

## 설치

[NuGet](https://www.nuget.org/packages/Anthropic)에서 패키지를 설치하세요:

```bash
dotnet add package Anthropic
```

## 요구 사항

이 라이브러리는 .NET Standard 2.0 이상이 필요합니다.

## 사용법

```csharp
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을 포함한 인증 옵션에 대해서는 [인증](https://platform.claude.com/docs/ko/manage-claude/authentication)을 참조하세요. API 키가 여러 워크스페이스에 액세스할 수 있는 [개인 또는 서비스 계정 키](https://platform.claude.com/docs/ko/manage-claude/authentication#key-types)인 경우, `anthropic-workspace-id` 요청 헤더에 워크스페이스 ID를 설정하세요. [워크스페이스 선택](https://platform.claude.com/docs/ko/manage-claude/authentication#select-a-workspace)에서 이 SDK에 대한 요청별 옵션을 확인할 수 있습니다.

## 클라이언트 구성

환경 변수를 사용하여 클라이언트를 구성합니다:

```csharp
using Anthropic;

// ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN 및 ANTHROPIC_BASE_URL 환경 변수를 사용하여 구성됩니다
AnthropicClient client = new();
```

또는 수동으로 구성합니다:

```csharp
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`를 호출하세요:

```csharp
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` 식](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/operators/with-expression)을 사용하면 수정된 옵션을 쉽게 구성할 수 있습니다.

`WithOptions` 메서드는 원래 클라이언트나 서비스에 영향을 주지 않습니다.

## 스트리밍

SDK는 응답 "청크" 스트림을 반환하는 메서드를 정의하며, 전체 응답을 기다리는 대신 각 청크가 도착하는 즉시 개별적으로 처리할 수 있습니다. "Streaming"(스트리밍) 메서드는 일반적으로 [SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) 또는 [JSONL](https://jsonlines.org) 응답에 해당합니다.

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

이러한 스트리밍 메서드는 [`IAsyncEnumerable`](https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.iasyncenumerable-1)을 반환합니다:

```csharp
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가 SDK에 요청을 재시도하거나 재시도하지 않도록 명시적으로 지시할 수도 있습니다.

사용자 정의 재시도 횟수를 설정하려면 `MaxRetries` 속성을 사용하여 클라이언트를 구성하세요:

```csharp
using Anthropic;

AnthropicClient client = new() { MaxRetries = 3 };
```

또는 `WithOptions`를 사용하여 단일 메서드 호출을 구성하세요:

```csharp
using System;

var message = await client
    .WithOptions(options =>
        options with { MaxRetries = 3 }
    )
    .Messages.Create(parameters);

Console.WriteLine(message);
```

## 타임아웃

요청은 기본적으로 10분 후에 타임아웃됩니다.

사용자 정의 타임아웃을 설정하려면 `Timeout` 옵션을 사용하여 클라이언트를 구성하세요:

```csharp
using System;
using Anthropic;

AnthropicClient client = new() { Timeout = TimeSpan.FromSeconds(42) };
```

또는 `WithOptions`를 사용하여 단일 메서드 호출을 구성하세요:

```csharp
using System;

var message = await client
    .WithOptions(options =>
        options with { Timeout = TimeSpan.FromSeconds(42) }
    )
    .Messages.Create(parameters);

Console.WriteLine(message);
```

## 페이지네이션

SDK는 페이지네이션된 결과 목록을 반환하는 메서드를 정의합니다. 결과를 한 번에 한 페이지씩 또는 모든 페이지에 걸쳐 항목별로 액세스할 수 있는 편리한 방법을 제공합니다.

### 자동 페이지네이션

모든 페이지에 걸쳐 모든 결과를 순회하려면 필요에 따라 자동으로 추가 페이지를 가져오는 `Paginate` 메서드를 사용하세요. 이 메서드는 [`IAsyncEnumerable`](https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.iasyncenumerable-1)을 반환합니다:

```csharp
using System;

var page = await client.Messages.Batches.List(parameters);
await foreach (var item in page.Paginate())
{
    Console.WriteLine(item);
}
```

### 수동 페이지네이션

개별 페이지 항목에 액세스하고 다음 페이지를 수동으로 요청하려면 `Items` 속성과 `HasNext` 및 `Next` 메서드를 사용하세요:

```csharp
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`를 호출하세요:

```csharp
var message = await client.Messages.Create(parameters);
message.Validate();
```

또는 `ResponseValidation` 옵션을 사용하여 클라이언트를 구성하세요:

```csharp
using Anthropic;

AnthropicClient client = new() { ResponseValidation = true };
```

또는 `WithOptions`를 사용하여 단일 메서드 호출을 구성하세요:

```csharp
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`와 직접 함께 사용할 수 있습니다.

```csharp
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`를 반환합니다:

```csharp
using System;
using Anthropic.Models.Files;

FileDownloadParams parameters = new() { FileID = "file_id" };

var response = await client.Files.Download(parameters);

Console.WriteLine(response);
```

응답 콘텐츠를 파일 또는 임의의 [`Stream`](https://learn.microsoft.com/en-us/dotnet/api/system.io.stream)에 저장하려면 [`CopyToAsync`](https://learn.microsoft.com/en-us/dotnet/api/system.io.stream.copytoasync) 메서드를 사용하세요:

```csharp
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`를 붙이세요:

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

원시 `HttpResponseMessage`는 `RawMessage` 속성을 통해서도 액세스할 수 있습니다.

비스트리밍 응답의 경우, 필요하다면 응답을 C# 클래스의 인스턴스로 역직렬화할 수 있습니다:

```csharp
using System;
using Anthropic.Models.Messages;

var response = await client.WithRawResponse.Messages.Create(parameters);
Message deserialized = await response.Deserialize();
Console.WriteLine(deserialized);
```

스트리밍 응답의 경우, 필요하다면 응답을 `IAsyncEnumerable`로 역직렬화할 수 있습니다:

```csharp
using System;

var response = await client.WithRawResponse.Messages.CreateStreaming(parameters);
await foreach (var item in response.Enumerate())
{
    Console.WriteLine(item);
}
```

### 로깅

<Warning>
  모든 로그 메시지는 디버깅 용도로만 제공됩니다. 로그 메시지의 형식과 내용은 릴리스 간에 변경될 수 있습니다.
</Warning>

환경 변수를 설정하여 디버그 로깅을 활성화하세요:

```bash
export ANTHROPIC_LOG=debug
```

### 문서화되지 않은 API 기능

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

## 플랫폼 통합

<Note>
  코드 예제가 포함된 자세한 플랫폼 설정 가이드는 다음을 참조하세요:

  * [Amazon Bedrock](https://platform.claude.com/docs/ko/build-with-claude/claude-in-amazon-bedrock)
  * [Amazon Bedrock (Opus 4.6 및 이전 버전)](https://platform.claude.com/docs/ko/build-with-claude/claude-on-amazon-bedrock-legacy)
  * [Claude Platform on AWS](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws)
  * [Google Cloud](https://platform.claude.com/docs/ko/build-with-claude/claude-on-vertex-ai)
  * [Microsoft Foundry](https://platform.claude.com/docs/ko/build-with-claude/claude-in-microsoft-foundry)
</Note>

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

* **Agent Platform:** `Anthropic.Vertex`. 클라이언트 설정은 [Google Cloud의 Claude](https://platform.claude.com/docs/ko/build-with-claude/claude-on-vertex-ai)를 참조하세요.
* **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](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#workspaces) 참조). 베타로 제공됩니다.
* **Foundry:** `Anthropic.Foundry`. `DefaultAnthropicFoundryCredentials.FromEnv()` 또는 명시적 자격 증명과 함께 `AnthropicFoundryClient`를 사용하세요.

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

## 시맨틱 버저닝

이 패키지는 일반적으로 [SemVer](https://semver.org/spec/v2.0.0.html) 규칙을 따르지만, 특정 하위 호환되지 않는 변경 사항이 마이너 버전으로 릴리스될 수 있습니다:

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

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

## 추가 리소스

* [GitHub 리포지토리](https://github.com/anthropics/anthropic-sdk-csharp)
* [NuGet 패키지](https://www.nuget.org/packages/Anthropic)
* [API 레퍼런스](https://platform.claude.com/docs/ko/api/overview)
* [메시지 스트리밍](https://platform.claude.com/docs/ko/build-with-claude/streaming)