---
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 이상([non-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를 사용한 스트리밍 응답을 지원합니다.

```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 })`를 사용할 수도 있습니다. 이 방식은 스트림 이벤트의 비동기 이터러블만 반환하므로 메모리를 더 적게 사용합니다(최종 메시지 객체를 대신 구성해 주지 않습니다).

## 도구 헬퍼

이 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는 `anthropic-version` 헤더를 이 SDK 메이저 버전에 해당하는 API 버전([시맨틱 버저닝](https://platform.claude.com/docs/ko/cli-sdks-libraries/sdks/typescript#semantic-versioning) 참조)(으)로 설정하여 자동으로 전송합니다.

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

이렇게 하면 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
});
```

### OpenTelemetry 추적

애플리케이션이 OpenTelemetry 트레이서 프로바이더를 등록하면 SDK는 전송하는 각 요청에 대해 스팬을 내보냅니다. 스팬을 관측성 플랫폼으로 전송하려면 [Claude SDK에서 OpenTelemetry 설정하기](https://platform.claude.com/docs/ko/manage-claude/opentelemetry/sdk)를 참조하세요.

### 사용자 지정/문서화되지 않은 요청 보내기

이 라이브러리는 문서화된 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)
  * [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/ko/build-with-claude/claude-models-on-google-cloud/google-managed)
  * [Microsoft Foundry](https://platform.claude.com/docs/ko/build-with-claude/claude-in-microsoft-foundry)

  [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/ko/build-with-claude/claude-models-on-google-cloud/anthropic-managed)도 참조하세요.
</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를 사용하는 기존 애플리케이션을 위해 유지됩니다.

TypeScript SDK는 `AnthropicGoogleCloud` 클라이언트를 통해 Claude Models on Google Cloud (Anthropic managed)도 지원합니다. 이 클라이언트는 베타 버전입니다. 설치하려면 `npm install @anthropic-ai/google-cloud-sdk`를 실행하세요. 생성자에 `workspaceId`를 전달하거나 `ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID` 환경 변수를 설정하세요. 클라이언트가 워크스페이스 ID를 확인하는 방법은 [프로젝트, 위치 및 워크스페이스 확인](https://platform.claude.com/docs/ko/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution)을 참조하세요.

## 시맨틱 버저닝

이 SDK의 각 메이저 버전은 기본적으로 `anthropic-version` 헤더에 하나의 API 버전을 전송하며, 새로운 API 버전이 나올 때마다 새로운 메이저 버전이 함께 출시됩니다. `2026-10-21`을 전송하는 첫 번째 메이저 버전은 1.0.0입니다. [API 버전 2026-10-21로 마이그레이션](https://platform.claude.com/docs/ko/api/migration-2026-10-21#upgrade)을 참조하세요.

이 패키지는 일반적으로 [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)