---
title: TypeScript SDK
url: https://platform.claude.com/docs/ko/cli-sdks-libraries/sdks/typescript
description: Node.js, Deno, Bun 및 브라우저 환경을 위한 Anthropic TypeScript SDK 설치 및 구성
---

이 라이브러리는 TypeScript 또는 JavaScript에서 Claude API에 편리하게 접근할 수 있도록 합니다.

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

## 설치

```bash
npm install @anthropic-ai/sdk
```

## 요구 사항

TypeScript >= 5.0을 지원합니다.

다음 런타임이 지원됩니다:

* Node.js 20 LTS 이상([EOL이 아닌](https://endoflife.date/nodejs)) 버전.
* Deno v1.28.0 이상.
* Bun 1.0 이상.
* Cloudflare Workers.
* Vercel Edge Runtime.
* `"node"` 환경을 사용하는 Jest 28 이상(`"jsdom"`은 현재 지원되지 않습니다).
* Nitro v2.6 이상.
* 웹 브라우저: 비밀 API 자격 증명이 노출되는 것을 방지하기 위해 기본적으로 비활성화되어 있습니다([API 키 모범 사례](https://support.claude.com/en/articles/9767949-api-key-best-practices-keeping-your-keys-safe-and-secure) 참조). `dangerouslyAllowBrowser`를 명시적으로 `true`로 설정하여 브라우저 지원을 활성화할 수 있습니다.

React Native는 현재 지원되지 않습니다.

다른 런타임 환경에 관심이 있으시면 [GitHub 저장소](https://github.com/anthropics/anthropic-sdk-typescript)에서 이슈를 열거나 추천(upvote)해 주세요.

## 사용법

```typescript
const client = new Anthropic({
  apiKey: process.env["ANTHROPIC_API_KEY"] // This is the default and can be omitted
});

const message = await client.messages.create({
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  model: "claude-opus-5-5"
});

for (const block of message.content) {
  if (block.type === "text") {
    console.log(block.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에 대한 요청별 옵션을 확인할 수 있습니다.

## 요청 및 응답 타입

이 라이브러리에는 모든 요청 매개변수와 응답 필드에 대한 TypeScript 정의가 포함되어 있습니다. 다음과 같이 가져와서 사용할 수 있습니다:

```typescript
const client = new Anthropic({
  apiKey: process.env["ANTHROPIC_API_KEY"] // This is the default and can be omitted
});

const params: Anthropic.MessageCreateParams = {
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  model: "claude-opus-5-5"
};
const message: Anthropic.Message = await client.messages.create(params);
```

각 메서드, 요청 매개변수 및 응답 필드에 대한 문서는 docstring으로 제공되며 대부분의 최신 편집기에서 마우스를 올리면 표시됩니다.

## 토큰 계산

`usage` 응답 속성을 통해 특정 요청의 정확한 사용량을 확인할 수 있습니다. 예를 들어:

```typescript
const message = await client.messages.create({
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  model: "claude-opus-5-5"
});
console.log(message.usage);
// { input_tokens: 25, output_tokens: 13 }
```

## 스트리밍 응답

SDK는 "Server-Sent Events"(서버 전송 이벤트), 즉 SSE를 사용한 "streaming"(스트리밍) 응답을 지원합니다.

```typescript
const client = new Anthropic();

const stream = await client.messages.create({
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  model: "claude-opus-5-5",
  stream: true
});
for await (const messageStreamEvent of stream) {
  console.log(messageStreamEvent.type);
}
```

스트림을 취소해야 하는 경우 루프에서 `break`하거나 `stream.controller.abort()`를 호출할 수 있습니다.

## 스트리밍 헬퍼

이 라이브러리는 메시지 스트리밍을 위한 여러 편의 기능을 제공합니다. 예를 들어:

```typescript
const anthropic = new Anthropic();

const stream = anthropic.messages
  .stream({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    messages: [
      {
        role: "user",
        content: "Say hello there!"
      }
    ]
  })
  .on("text", (text) => {
    console.log(text);
  });

const message = await stream.finalMessage();
console.log(message);
```

`client.messages.stream(...)`을 사용한 스트리밍은 이벤트 핸들러 및 누적 기능을 포함하여 편의를 위한 다양한 헬퍼를 제공합니다.

또는 `client.messages.create({ ..., stream: true })`를 사용할 수 있습니다. 이 방식은 스트림 내 이벤트의 async iterable만 반환하므로 메모리를 덜 사용합니다(최종 메시지 객체를 생성해 주지 않습니다).

## 도구 헬퍼

이 SDK는 Messages API에서 도구를 쉽게 생성하고 실행할 수 있도록 헬퍼를 제공합니다. Zod 스키마 또는 JSON Schema를 사용하여 도구의 입력을 기술할 수 있습니다. 그런 다음 `client.beta.messages.toolRunner()` 메서드를 사용하여 해당 도구를 실행할 수 있습니다. 이 메서드는 선택한 모델이 생성한 입력을 올바른 도구에 전달하고 그 결과를 다시 모델에 전달하는 작업을 처리합니다.

"Tool use"(도구 사용)에 대한 자세한 내용은 [Claude와 함께하는 도구 사용](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/overview)을 참조하세요. 이 SDK로 브라우저 사용 도구 또는 컴퓨터 사용 도구를 실행하려면 [SDK 도구 세트를 사용한 브라우저 및 컴퓨터 사용](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/browser-use-sdk)을 참조하세요.

```typescript
import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
import { z } from "zod";

const anthropic = new Anthropic();

const weatherTool = betaZodTool({
  name: "get_weather",
  inputSchema: z.object({
    location: z.string()
  }),
  description: "Get the current weather in a given location",
  run: (input) => {
    return `The weather in ${input.location} is foggy and 60°F`;
  }
});

const finalMessage = await anthropic.beta.messages.toolRunner({
  model: "claude-opus-5-5",
  max_tokens: 1000,
  messages: [{ role: "user", content: "What is the weather in San Francisco?" }],
  tools: [weatherTool]
});

console.log(finalMessage.content);
```

### 도구 오류

도구에서 발생한 오류를 모델에 보고하려면 `run` 함수에서 `ToolError`를 throw하세요. 일반 `Error`와 달리 `ToolError`는 콘텐츠 블록을 받을 수 있으므로 오류 응답에 이미지나 기타 구조화된 콘텐츠를 포함할 수 있습니다:

```typescript
import { ToolError } from "@anthropic-ai/sdk/lib/tools/BetaRunnableTool";

const screenshotTool = betaZodTool({
  name: "take_screenshot",
  inputSchema: z.object({ url: z.string() }),
  run: async (input) => {
    if (!isValidUrl(input.url)) {
      throw new ToolError(`Invalid URL: ${input.url}`);
    }
    const result = await takeScreenshot(input.url);
    if (result.error) {
      // 모델이 무엇이 잘못되었는지 볼 수 있도록 오류 스크린샷을 포함합니다
      throw new ToolError([
        { type: "text", text: `Failed to load page: ${result.error}` },
        {
          type: "image",
          source: { type: "base64", data: result.screenshot, media_type: "image/png" }
        }
      ]);
    }
    return {
      type: "image",
      source: { type: "base64", data: result.screenshot, media_type: "image/png" }
    };
  }
});
```

일반 `Error`가 throw되면 메시지는 텍스트 콘텐츠 블록으로 변환됩니다.

## 도구 사용

이 SDK는 함수 호출(function calling)이라고도 하는 도구 사용을 지원합니다. 자세한 내용은 [Claude와 함께하는 도구 사용](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/overview)을 참조하세요.

## MCP 헬퍼

이 SDK는 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 서버와의 통합을 위한 헬퍼를 제공합니다. 이 헬퍼들은 MCP 타입을 Claude API 타입으로 변환하여 MCP 도구, 프롬프트 및 리소스를 다룰 때 보일러플레이트를 줄여 줍니다.

<Tip>
  Claude API는 Claude가 원격 MCP 서버에 직접 연결할 수 있게 하는 [`mcp_servers` 매개변수](https://platform.claude.com/docs/ko/agents-and-tools/mcp-connector)도 지원합니다. URL로 접근 가능한 원격 서버가 있고 도구 지원만 필요한 경우 `mcp_servers`를 사용하세요. 로컬 MCP 서버, 프롬프트, 리소스가 필요하거나 MCP 연결을 더 세밀하게 제어해야 하는 경우 MCP 헬퍼를 사용하세요.
</Tip>

```typescript
import {
  mcpTools,
  mcpMessages,
  mcpResourceToContent,
  mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const anthropic = new Anthropic();

// MCP 서버에 연결합니다
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);

// MCP 프롬프트를 사용합니다
const { messages } = await mcpClient.getPrompt({ name: "my-prompt" });
const response = await anthropic.beta.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});
console.log(response.content);

// toolRunner로 MCP 도구를 사용합니다
const { tools } = await mcpClient.listTools();
const finalMessage = await anthropic.beta.messages.toolRunner({
  model: "claude-opus-5-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Use the available tools" }],
  tools: mcpTools(tools, mcpClient)
});
console.log(finalMessage.content);

// MCP 리소스를 콘텐츠로 사용합니다
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
await anthropic.beta.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        mcpResourceToContent(resource),
        { type: "text", text: "Summarize this document" }
      ]
    }
  ]
});

// MCP 리소스를 파일로 업로드합니다
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
await anthropic.files.upload({ file: mcpResourceToFile(fileResource) });
```

### MCP 오류 처리

변환 함수는 MCP 값이 Claude API에서 지원되지 않는 경우(예: 지원되지 않는 콘텐츠 타입, 지원되지 않는 MIME 타입, HTTP/HTTPS가 아닌 리소스 링크) `UnsupportedMCPValueError`를 throw합니다.

## 메시지 배치

이 SDK는 `client.messages.batches` 네임스페이스에서 [배치 처리](https://platform.claude.com/docs/ko/build-with-claude/batch-processing)를 지원합니다.

### 배치 생성

Message Batches는 요청 배열을 받으며, 각 객체는 `custom_id` 식별자와 표준 Messages API와 정확히 동일한 요청 `params`를 가집니다:

```typescript
const batch = await client.messages.batches.create({
  requests: [
    {
      custom_id: "my-first-request",
      params: {
        model: "claude-opus-5-5",
        max_tokens: 1024,
        messages: [{ role: "user", content: "Hello, world" }]
      }
    },
    {
      custom_id: "my-second-request",
      params: {
        model: "claude-opus-5-5",
        max_tokens: 1024,
        messages: [{ role: "user", content: "Hi again, friend" }]
      }
    }
  ]
});
```

### 배치 결과 가져오기

Message Batch 처리가 완료되면(`.processing_status === 'ended'`로 표시됨) `.batches.results()`로 결과에 접근할 수 있습니다.

```typescript
const results = await client.messages.batches.results(batch.id);
for await (const entry of results) {
  if (entry.result.type === "succeeded") {
    console.log(entry.result.message.content);
  }
}
```

## 파일 업로드

파일 업로드에 해당하는 요청 매개변수는 다양한 형태로 전달할 수 있습니다:

* `File`(또는 동일한 구조를 가진 객체)
* `fetch` `Response`(또는 동일한 구조를 가진 객체)
* `fs.ReadStream`
* `toFile` 헬퍼의 반환값

Files API는 콘텐츠 타입을 자동으로 추론하지 않으므로 명시적으로 설정하세요:

```typescript
import fs from "node:fs";
import Anthropic, { toFile } from "@anthropic-ai/sdk";

const client = new Anthropic();

// Node `fs`에 접근할 수 있다면 `fs.createReadStream()`을 사용하세요:
await client.files.upload({
  file: await toFile(fs.createReadStream("/path/to/file"), undefined, {
    type: "application/json"
  })
});

// 또는 웹 `File` API가 있다면 `File` 인스턴스를 전달할 수 있습니다:
await client.files.upload({
  file: new File(["my bytes"], "file.txt", { type: "text/plain" })
});
// `fetch` `Response`를 전달할 수도 있습니다:
await client.files.upload({
  file: await fetch("https://somesite/file")
});

// 또는 `Buffer` / `Uint8Array`
await client.files.upload({
  file: await toFile(Buffer.from("my bytes"), "file", { type: "text/plain" })
});
await client.files.upload({
  file: await toFile(new Uint8Array([0, 1, 2]), "file", { type: "text/plain" })
});
```

## 오류 처리

라이브러리가 API에 연결할 수 없거나 API가 성공이 아닌 상태 코드(즉, 4xx 또는 5xx 응답)를 반환하는 경우 `APIError`의 하위 클래스가 throw됩니다:

```typescript
const message = await client.messages
  .create({
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5-5"
  })
  .catch(async (err) => {
    if (err instanceof Anthropic.APIError) {
      console.log(err.status); // 400
      console.log(err.name); // BadRequestError
      console.log(err.headers); // {server: 'nginx', ...}
    } else {
      throw err;
    }
  });
```

오류 코드는 다음과 같습니다:

| 상태 코드 | 오류 타입                      |
| ----- | -------------------------- |
| 400   | `BadRequestError`          |
| 401   | `AuthenticationError`      |
| 403   | `PermissionDeniedError`    |
| 404   | `NotFoundError`            |
| 409   | `ConflictError`            |
| 422   | `UnprocessableEntityError` |
| 429   | `RateLimitError`           |
| >=500 | `InternalServerError`      |
| N/A   | `APIConnectionError`       |

## 요청 ID

> 요청 디버깅에 대한 자세한 내용은 [요청 ID](https://platform.claude.com/docs/ko/api/errors#request-id)를 참조하세요.

SDK의 모든 객체 응답은 `request-id` 응답 헤더에서 추가된 `_request_id` 속성을 제공하므로, 실패한 요청을 빠르게 로깅하고 Anthropic에 보고할 수 있습니다.

```typescript
const message = await client.messages.create({
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  model: "claude-opus-5-5"
});
console.log(message._request_id); // req_018EeWyXxfu5pfWkrYcMdjWG
```

## 재시도

특정 오류는 기본적으로 짧은 지수 백오프와 함께 2회 자동 재시도됩니다. 연결 오류(예: 네트워크 연결 문제로 인한), 408 Request Timeout, 409 Conflict, 429 Rate Limit 및 >=500 Internal 오류는 모두 기본적으로 재시도됩니다.

`maxRetries` 옵션을 사용하여 이를 구성하거나 비활성화할 수 있습니다:

```typescript
// 모든 요청에 대한 기본값을 구성합니다:
const client = new Anthropic({
  maxRetries: 0 // default is 2
});

// 또는 요청별로 구성합니다:
await client.messages.create(
  {
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5-5"
  },
  { maxRetries: 5 }
);
```

## 타임아웃

기본적으로 요청은 10분 후에 타임아웃됩니다. 그러나 큰 `max_tokens` 값을 지정하고 스트리밍을 사용하지 *않는* 경우, 기본 타임아웃은 다음 공식을 사용하여 동적으로 계산됩니다:

```typescript
const minimum = 10 * 60;
const calculated = (60 * 60 * maxTokens) / 128_000;
return calculated < minimum ? minimum * 1000 : calculated * 1000;
```

이는 요청 또는 클라이언트 수준에서 재정의하지 않는 한, `max_tokens` 매개변수에 따라 조정되어 최대 60분까지의 타임아웃이 됩니다.

`timeout` 옵션으로 이를 구성할 수 있습니다:

```typescript
// 모든 요청에 대한 기본값을 구성합니다:
const client = new Anthropic({
  timeout: 20 * 1000 // 20 seconds (default is 10 minutes)
});

// 요청별로 재정의합니다:
await client.messages.create(
  {
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5-5"
  },
  { timeout: 5 * 1000 }
);
```

타임아웃 시 `APIConnectionTimeoutError`가 throw됩니다.

타임아웃된 요청은 [기본적으로 두 번 재시도](https://platform.claude.com/docs/ko/cli-sdks-libraries/sdks/typescript#retries)됩니다.

## 긴 요청

<Warning>
  오래 실행되는 요청에는 스트리밍 [Messages API](https://platform.claude.com/docs/ko/cli-sdks-libraries/sdks/typescript#streaming-responses) 사용을 고려하세요.
</Warning>

스트리밍을 사용하지 않고 큰 `max_tokens` 값을 설정하는 것은 피하세요. 일부 네트워크는 일정 시간이 지나면 유휴 연결을 끊을 수 있으며, 이로 인해 Anthropic으로부터 응답을 받지 못한 채 요청이 실패하거나 [타임아웃](https://platform.claude.com/docs/ko/cli-sdks-libraries/sdks/typescript#timeouts)될 수 있습니다.

이 SDK는 또한 비스트리밍 요청이 대략 10분 이상 걸릴 것으로 예상되는 경우 오류를 throw합니다. `stream: true`를 전달하거나 클라이언트 또는 요청 수준에서 `timeout` 옵션을 [재정의](https://platform.claude.com/docs/ko/cli-sdks-libraries/sdks/typescript#timeouts)하면 이 오류가 비활성화됩니다.

비스트리밍 요청에서 예상 요청 "latency"(지연 시간)가 [타임아웃](https://platform.claude.com/docs/ko/cli-sdks-libraries/sdks/typescript#timeouts)보다 길면 클라이언트가 응답을 받지 못한 채 연결을 종료하고 재시도하게 됩니다.

`fetch` 구현에서 지원되는 경우, SDK는 일부 네트워크에서 유휴 연결 타임아웃의 영향을 줄이기 위해 [TCP 소켓 keep-alive](https://tldp.org/HOWTO/TCP-Keepalive-HOWTO/overview.html) 옵션을 설정합니다. 이는 사용자 정의 프록시를 구성하여 [재정의](https://platform.claude.com/docs/ko/cli-sdks-libraries/sdks/typescript#configuring-proxies)할 수 있습니다.

## 자동 페이지네이션

Claude API의 목록 메서드는 페이지네이션됩니다. `for await ... of` 구문을 사용하여 모든 페이지에 걸쳐 항목을 순회할 수 있습니다:

```typescript
async function fetchAllMessageBatches() {
  const allMessageBatches = [];
  // 필요에 따라 추가 페이지를 자동으로 가져옵니다.
  for await (const messageBatch of client.messages.batches.list({ limit: 20 })) {
    allMessageBatches.push(messageBatch);
  }
  return allMessageBatches;
}
```

또는 한 번에 한 페이지씩 요청할 수 있습니다:

```typescript
let page = await client.messages.batches.list({ limit: 20 });
for (const messageBatch of page.data) {
  console.log(messageBatch);
}

// 수동 페이지네이션을 위한 편의 메서드가 제공됩니다:
while (page.hasNextPage()) {
  page = await page.getNextPage();
  // ...
}
```

## 기본 헤더

SDK는 `2023-06-01`로 설정된 `anthropic-version` 헤더를 자동으로 전송합니다.

필요한 경우 요청별로 기본 헤더를 설정하여 이를 재정의할 수 있습니다.

이렇게 하면 SDK에서 잘못된 타입 및 기타 예기치 않거나 정의되지 않은 동작이 발생할 수 있다는 점에 유의하세요.

```typescript
const client = new Anthropic();

const message = await client.messages.create(
  {
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5-5"
  },
  { headers: { "anthropic-version": "My-Custom-Value" } }
);
```

## 고급 사용법

### 원시 Response 데이터 접근(예: 헤더)

`fetch()`가 반환하는 "원시" `Response`는 모든 메서드가 반환하는 `APIPromise` 타입의 `.asResponse()` 메서드를 통해 접근할 수 있습니다. 이 메서드는 성공적인 응답의 헤더를 수신하는 즉시 반환되며 응답 본문을 소비하지 않으므로, 사용자 정의 파싱 또는 스트리밍 로직을 자유롭게 작성할 수 있습니다.

`.withResponse()` 메서드를 사용하여 파싱된 데이터와 함께 원시 `Response`를 얻을 수도 있습니다. `.asResponse()`와 달리 이 메서드는 본문을 소비하며, 파싱이 완료되면 반환됩니다.

```typescript
const client = new Anthropic();

const response = await client.messages
  .create({
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5-5"
  })
  .asResponse();
console.log(response.headers.get("X-My-Header"));
console.log(response.statusText); // access the underlying Response object

const { data: message, response: raw } = await client.messages
  .create({
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5-5"
  })
  .withResponse();
console.log(raw.headers.get("X-My-Header"));
console.log(message.content);
```

### 로깅

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

#### 로그 레벨

로그 레벨은 두 가지 방법으로 구성할 수 있습니다:

1. `ANTHROPIC_LOG` 환경 변수를 통해
2. `logLevel` 클라이언트 옵션 사용(설정된 경우 환경 변수를 재정의함)

```typescript
const client = new Anthropic({
  logLevel: "debug" // Show all log messages
});
```

사용 가능한 로그 레벨(가장 상세한 것부터 가장 간략한 것 순):

* `'debug'` - 디버그 메시지, 정보, 경고 및 오류 표시
* `'info'` - 정보 메시지, 경고 및 오류 표시
* `'warn'` - 경고 및 오류 표시(기본값)
* `'error'` - 오류만 표시
* `'off'` - 모든 로깅 비활성화

`'debug'` 레벨에서는 헤더와 본문을 포함한 모든 HTTP 요청 및 응답이 로깅됩니다. 일부 인증 관련 헤더는 가려지지만, 요청 및 응답 본문의 민감한 데이터는 여전히 표시될 수 있습니다.

#### 사용자 정의 로거

기본적으로 이 라이브러리는 `globalThis.console`에 로깅합니다. 사용자 정의 로거를 제공할 수도 있습니다. [pino](https://www.npmjs.com/package/pino), [winston](https://www.npmjs.com/package/winston), [bunyan](https://www.npmjs.com/package/bunyan), [consola](https://www.npmjs.com/package/consola), [signale](https://www.npmjs.com/package/signale), [@std/log](https://jsr.io/@std/log)를 포함한 대부분의 로깅 라이브러리가 지원됩니다. 로거가 작동하지 않으면 이슈를 열어 주세요.

사용자 정의 로거를 제공하는 경우에도 `logLevel` 옵션이 어떤 메시지를 내보낼지 제어합니다. 구성된 레벨보다 낮은 메시지는 로거로 전송되지 않습니다.

```typescript
import pino from "pino";

const logger = pino();

const client = new Anthropic({
  logger: logger.child({ name: "Anthropic" }),
  logLevel: "debug" // Send all messages to pino, allowing it to filter
});
```

### 사용자 정의/문서화되지 않은 요청 만들기

이 라이브러리는 문서화된 API에 편리하게 접근할 수 있도록 타입이 지정되어 있습니다. 문서화되지 않은 엔드포인트, 매개변수 또는 응답 속성에 접근해야 하는 경우에도 라이브러리를 사용할 수 있습니다.

#### 문서화되지 않은 엔드포인트

문서화되지 않은 엔드포인트에 요청하려면 `client.get`, `client.post` 및 기타 HTTP 동사를 사용할 수 있습니다. 재시도와 같은 클라이언트 옵션은 이러한 요청을 할 때도 적용됩니다.

```typescript
await client.post("/some/path", {
  body: { some_prop: "foo" },
  query: { some_query_arg: "bar" }
});
```

#### 문서화되지 않은 요청 매개변수

문서화되지 않은 매개변수를 사용하여 요청하려면 해당 매개변수에 `// @ts-expect-error`를 사용할 수 있습니다. 이 라이브러리는 요청이 타입과 일치하는지 런타임에 검증하지 않으므로, 전송하는 추가 값은 그대로 전송됩니다.

```typescript
client.messages.create({
  // ...
  // @ts-expect-error baz is not yet public
  baz: "undocumented option"
});
```

`GET` 동사를 사용하는 요청의 경우 추가 매개변수는 쿼리에 포함되며, 다른 모든 요청은 추가 매개변수를 본문에 담아 전송합니다.

추가 인수를 명시적으로 전송하려면 `query`, `body`, `headers` 요청 옵션을 사용할 수 있습니다.

#### 문서화되지 않은 응답 속성

문서화되지 않은 응답 속성에 접근하려면 응답 객체에 `// @ts-expect-error`를 사용하여 접근하거나, 응답 객체를 필요한 타입으로 캐스팅할 수 있습니다. 요청 매개변수와 마찬가지로 SDK는 API 응답의 추가 속성을 검증하거나 제거하지 않습니다.

### fetch 클라이언트 사용자 정의

기본적으로 이 라이브러리는 전역 `fetch` 함수가 정의되어 있다고 가정합니다.

다른 `fetch` 함수를 사용하려면 전역을 폴리필할 수 있습니다:

```typescript
import fetch from "my-fetch";

globalThis.fetch = fetch;
```

또는 클라이언트에 전달할 수 있습니다:

```typescript
import fetch from "my-fetch";

const client = new Anthropic({ fetch });
```

### Fetch 옵션

`fetch` 함수를 재정의하지 않고 사용자 정의 `fetch` 옵션을 설정하려면, 클라이언트를 생성하거나 요청할 때 `fetchOptions` 객체를 제공할 수 있습니다. (요청별 옵션이 클라이언트 옵션을 재정의합니다.)

```typescript
const client = new Anthropic({
  fetchOptions: {
    // `RequestInit` 옵션
  }
});
```

### 프록시 구성

프록시 동작을 수정하려면 런타임별 프록시 옵션을 요청에 추가하는 사용자 정의 `fetchOptions`를 제공할 수 있습니다:

<Tabs>
  <Tab title="Node.js">
    ```typescript
    import * as undici from "undici";

    const proxyAgent = new undici.ProxyAgent("http://localhost:8888");
    const client = new Anthropic({
      fetchOptions: {
        dispatcher: proxyAgent
      }
    });
    ```
  </Tab>

  <Tab title="Bun">
    ```typescript
    const client = new Anthropic({
      fetchOptions: {
        proxy: "http://localhost:8888"
      }
    });
    ```
  </Tab>

  <Tab title="Deno">
    ```typescript
    import Anthropic from "npm:@anthropic-ai/sdk";

    const httpClient = Deno.createHttpClient({ proxy: { url: "http://localhost:8888" } });
    const client = new Anthropic({
      fetchOptions: {
        client: httpClient
      }
    });
    ```
  </Tab>
</Tabs>

## 베타 기능

베타 기능은 초기 피드백을 받고 새로운 기능을 테스트하기 위해 정식 출시 전에 제공됩니다. Claude의 모든 기능과 도구의 가용성은 [기능 개요](https://platform.claude.com/docs/ko/build-with-claude/overview)에서 확인할 수 있습니다.

대부분의 베타 API 기능은 클라이언트의 `beta` 속성을 통해 접근할 수 있습니다. 특정 베타 기능을 활성화하려면 메시지를 생성할 때 `betas` 필드에 적절한 [베타 헤더](https://platform.claude.com/docs/ko/api/beta-headers)를 추가해야 합니다.

예를 들어, [컨텍스트 편집](https://platform.claude.com/docs/ko/build-with-claude/context-editing)을 활성화하려면:

```typescript
const client = new Anthropic();
const response = await client.beta.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  betas: ["context-management-2025-06-27"]
});
```

## 런타임 지원

<Accordion title="브라우저 사용">
  `dangerouslyAllowBrowser` 옵션을 활성화하면 클라이언트 측 코드에 비밀 API 자격 증명이 노출되므로 위험할 수 있습니다. 웹 브라우저는 본질적으로 서버 환경보다 보안성이 낮습니다. 브라우저에 접근할 수 있는 모든 사용자가 이러한 자격 증명을 검사하고, 추출하고, 오용할 가능성이 있습니다. 이로 인해 자격 증명을 사용한 무단 접근이 발생하고 민감한 데이터나 기능이 손상될 수 있습니다.

  **언제 위험하지 않을 수 있나요?**

  브라우저 지원을 활성화해도 큰 위험이 없을 수 있는 특정 시나리오:

  * **내부 도구:** 애플리케이션이 사용자를 신뢰할 수 있는 통제된 내부 환경에서만 사용되는 경우, 자격 증명 노출 위험을 완화할 수 있습니다.
  * **개발 또는 디버깅 목적:** 자격 증명이 단기간만 유효하거나, 프로덕션 환경에서 함께 사용되지 않거나, 자주 교체되는 경우 이 기능을 일시적으로 활성화하는 것이 허용될 수 있습니다.
</Accordion>

## 플랫폼 통합

<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>

TypeScript SDK는 다음 플랫폼을 지원합니다:

* **Agent Platform:** `npm install @anthropic-ai/vertex-sdk`: `AnthropicVertex` 클라이언트 제공
* **Bedrock:** `npm install @anthropic-ai/bedrock-sdk`: `AnthropicBedrockMantle` 클라이언트 및 `bedrock-runtime` 경로용 `AnthropicBedrock` 제공
* **Claude Platform on AWS:** `npm install @anthropic-ai/aws-sdk`: `AnthropicAws` 클라이언트 제공. 생성자에 `workspaceId`를 전달하거나 `ANTHROPIC_AWS_WORKSPACE_ID` 환경 변수를 설정하세요. 베타로 제공됩니다.
* **Foundry:** `npm install @anthropic-ai/foundry-sdk`: `AnthropicFoundry` 클라이언트 제공

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

## 시맨틱 버저닝

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

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

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

## 자주 묻는 질문

FAQ, 이슈 및 커뮤니티 지원은 [GitHub 저장소](https://github.com/anthropics/anthropic-sdk-typescript)를 참조하세요.

## 추가 리소스

* [GitHub 저장소](https://github.com/anthropics/anthropic-sdk-typescript)
* [API 레퍼런스](https://platform.claude.com/docs/ko/api/overview)
* [메시지 스트리밍](https://platform.claude.com/docs/ko/build-with-claude/streaming)
* [Claude와 함께하는 도구 사용](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/overview)