TypeScript SDK

TypeScript SDK

이 라이브러리는 TypeScript나 JavaScript에서 Claude API에 편리하게 접근할 수 있게 해줘요. Node.js, Deno, Bun, Cloudflare Workers, 브라우저 등 다양한 런타임을 지원해요. 이 페이지에서는 설치, 사용법, 스트리밍, 도구 헬퍼, MCP 헬퍼, 에러 처리, 재시도, 페이지네이션 등을 다뤄요.

API 기능 문서와 코드 예시는 API 참조를 보세요. 이 페이지는 TypeScript 특정 SDK 기능과 설정을 다뤄요.

출처: 문서

본문

설치 (Installation)

npm install @anthropic-ai/sdk

요구사항 (Requirements)

TypeScript >= 5.0이 지원돼요. 다음 런타임이 지원돼요:

• Node.js 20 LTS 이상 (non-EOL 버전).
• Deno v1.28.0 이상.
• Bun 1.0 이상.
• Cloudflare Workers.
• Vercel Edge Runtime.
• "node" 환경의 Jest 28 이상("jsdom"은 현재 지원되지 않아요).
• Nitro v2.6 이상.
• 웹 브라우저: 비밀 API 자격 증명이 노출되는 걸 피하려고 기본적으로 비활성화돼요(API 키 모범 사례 참조). dangerouslyAllowBrowser를 명시적으로 true로 설정하면 브라우저 지원을 켤 수 있어요.

현재 React Native는 지원되지 않아요. 다른 런타임 환경에 관심이 있다면 GitHub 저장소에서 이슈를 열거나 투표해 주세요.

사용법 (Usage)

const client = new Anthropic({
  apiKey: proces...EY"] // 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 포함)은 인증을 보세요. API 키가 개인 또는 서비스 계정 키로서 여러 워크스페이스에 접근할 수 있다면 anthropic-workspace-id 요청 헤더에 워크스페이스 ID를 설정하세요. 워크스페이스 선택에서 이 SDK의 요청별 옵션을 보여줘요.

요청과 응답 타입 (Request and response types)

이 라이브러리에는 모든 요청 파라미터와 응답 필드에 대한 TypeScript 정의가 포함돼요. 다음과 같이 import해서 사용할 수 있어요:

const client = new Anthropic({
  apiKey: proces...EY"] // 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에 있으며 대부분의 최신 에디터에서 hover 시 나타나요.

토큰 계산 (Counting tokens)

특정 요청에 대한 정확한 사용량은 usage 응답 프로퍼티로 볼 수 있어요. 예를 들어:

const message = await client.messages.create(/* ... */);
console.log(message.usage);
// { input_tokens: 25, output_tokens: 13 }

스트리밍 응답 (Streaming responses)

SDK는 SSE(Server Sent Events)를 사용한 스트리밍 응답을 지원해요.

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()를 호출할 수 있어요.

스트리밍 헬퍼 (Streaming helpers)

이 라이브러리는 메시지 스트리밍을 위한 몇 가지 편의 기능을 제공해요. 예를 들어:

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 })를 쓸 수 있는데, 이는 스트림의 이벤트만 비동기 이터러블로 반환하므로 메모리를 덜 써요(최종 메시지 객체를 만들어 주지 않아요).

도구 헬퍼 (Tool helpers)

이 SDK는 Messages API에서 도구를 쉽게 만들고 실행할 수 있는 헬퍼를 제공해요. 도구 입력을 설명할 때 Zod 스키마나 JSON Schema를 쓸 수 있어요. 그런 다음 client.beta.messages.toolRunner() 메서드로 도구를 실행할 수 있어요. 이 메서드는 선택된 모델이 생성한 입력을 올바른 도구에 전달하고 결과를 다시 모델에 전달하는 일을 처리해요.

도구 사용에 대한 자세한 내용은 Claude와 함께하는 도구 사용을 보세요.

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

도구 에러 (Tool errors)

도구에서 모델로 에러를 보고하려면 run 함수에서 ToolError를 던지세요. 일반 Error와 달리 ToolError는 콘텐츠 블록을 받아서 에러 응답에 이미지나 다른 구조화된 콘텐츠를 포함할 수 있어요:

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) {
      // Include the error screenshot so the model can see what went wrong
      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가 던져지면 메시지가 텍스트 콘텐츠 블록으로 변환돼요.

도구 사용 (Tool use)

이 SDK는 function calling이라고도 알려진 도구 사용을 지원해요. 자세한 내용은 Claude와 함께하는 도구 사용을 보세요.

MCP 헬퍼 (MCP helpers)

이 SDK는 Model Context Protocol (MCP) 서버와 통합하기 위한 헬퍼를 제공해요. 이 헬퍼는 MCP 타입을 Claude API 타입으로 변환해서 MCP 도구, 프롬프트, 리소스를 작업할 때 보일러플레이트를 줄여줘요.

팁: Claude API는 Claude가 원격 MCP 서버에 직접 연결할 수 있는 mcp_servers 파라미터도 지원해요. URL로 접근 가능한 원격 서버가 있고 도구 지원만 필요한 경우 mcp_servers를 쓰세요. 로컬 MCP 서버, 프롬프트, 리소스가 필요하거나 MCP 연결을 더 제어하려면 MCP 헬퍼를 쓰세요.

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();

// Connect to an MCP server
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);

// Use MCP prompts
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);

// Use MCP tools with toolRunner
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);

// Use MCP resources as content
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" }
      ]
    }
  ]
});

// Upload MCP resources as files
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
await anthropic.files.upload({ file: mcpResourceToFile(fileResource) });

MCP 에러 처리 (MCP error handling)

변환 함수는 MCP 값이 Claude API에서 지원되지 않으면(예: 지원되지 않는 콘텐츠 타입, 지원되지 않는 MIME 타입, non-http/https 리소스 링크) UnsupportedMCPValueError를 던져요.

메시지 배치 (Message batches)

이 SDK는 client.messages.batches 네임스페이스 아래에서 배치 처리를 지원해요.

배치 만들기 (Creating a batch)

Message Batches는 요청 배열을 받아요. 각 객체에는 custom_id 식별자와 표준 Messages API와 동일한 요청 params가 있어요:

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" }]
      }
    }
  ]
});

배치에서 결과 가져오기 (Getting results from a batch)

Message Batch가 처리되면(.processing_status === 'ended'로 표시) .batches.results()로 결과에 접근할 수 있어요.

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

파일 업로드에 해당하는 요청 파라미터는 여러 형태로 전달할 수 있어요:

• File (또는 같은 구조의 객체)
• fetch Response (또는 같은 구조의 객체)
• fs.ReadStream
• toFile 헬퍼의 반환 값

파일 API가 추론해 주지 않으므로 content-type을 명시적으로 설정하세요:

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

const client = new Anthropic();

// If you have access to Node `fs`, use `fs.createReadStream()`:
await client.files.upload({
  file: await toFile(fs.createReadStream("/path/to/file"), undefined, {
    type: "application/json"
  })
});

// Or if you have the web `File` API you can pass a `File` instance:
await client.files.upload({
  file: new File(["my bytes"], "file.txt", { type: "text/plain" })
});
// You can also pass a `fetch` `Response`:
await client.files.upload({
  file: await fetch("https://somesite/file")
});

// Or a `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" })
});

에러 처리 (Handling errors)

라이브러리가 API에 연결할 수 없거나 API가 비성공 상태 코드(즉 4xx 또는 5xx 응답)를 반환하면 APIError의 하위 클래스가 던져져요:

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;
    }
  });

에러 코드는 다음과 같아요:

Status code	Error type
400	BadRequestError
401	AuthenticationError
403	PermissionDeniedError
404	NotFoundError
409	ConflictError
422	UnprocessableEntityError
429	RateLimitError
>=500	InternalServerError
N/A	APIConnectionError

요청 ID (Request IDs)

요청 디버깅에 대한 자세한 내용은 요청 ID를 보세요.

SDK의 모든 객체 응답에는 request-id 응답 헤더에서 추가된 _request_id 프로퍼티가 있어 실패한 요청을 빠르게 로그로 남기고 Anthropic에 보고할 수 있어요.

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

재시도 (Retries)

특정 에러는 기본적으로 2번 자동 재시도되며 짧은 지수 백오프를 사용해요. 연결 에러(네트워크 연결 문제 등), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal 에러가 모두 기본적으로 재시도돼요.

maxRetries 옵션으로 설정하거나 비활성화할 수 있어요:

// 모든 요청의 기본값 설정:
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 }
);

타임아웃 (Timeouts)

기본적으로 요청은 10분 후에 타임아웃돼요. 하지만 큰 max_tokens 값을 지정하고 스트리밍하지 않으면 기본 타임아웃이 다음 공식으로 동적으로 계산돼요:

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

요청 또는 클라이언트 레벨에서 덮어쓰지 않으면 max_tokens 파라미터에 따라 최대 60분까지 타임아웃이 조정돼요. timeout 옵션으로 설정할 수 있어요:

// 모든 요청의 기본값 설정:
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가 던져져요. 타임아웃된 요청은 기본적으로 두 번 재시도된다는 점을 유의하세요.

긴 요청 (Long requests)

주의: 더 긴 실행 요청에는 스트리밍 Messages API 사용을 고려하세요.

스트리밍 없이 큰 max_tokens 값을 설정하는 것은 피하세요. 일부 네트워크는 일정 시간 후 유휴 연결을 끊을 수 있어 Anthropic으로부터 응답을 받지 못하고 요청이 실패하거나 타임아웃될 수 있기 때문이에요.

이 SDK는 non-streaming 요청이 약 10분 이상 걸릴 것으로 예상되면 에러도 반환해요. stream: true를 전달하거나 클라이언트/요청 레벨에서 timeout 옵션을 덮어쓰면 이 에러가 비활성화돼요.

non-streaming 요청에 대한 타임아웃보다 긴 예상 요청 지연은 클라이언트가 응답을 받지 못하고 연결을 끊고 재시도하게 만들어요. fetch 구현이 지원하면 SDK는 TCP 소켓 keep-alive 옵션을 설정해 일부 네트워크에서 유휴 연결 타임아웃의 영향을 줄여요. 커스텀 프록시를 설정해서 덮어쓸 수 있어요.

자동 페이지네이션 (Auto-pagination)

Claude API의 목록 메서드는 페이지로 나뉘어요. for await ... of 문법으로 모든 페이지의 항목을 순회할 수 있어요:

async function fetchAllMessageBatches() {
  const allMessageBatches = [];
  // Automatically fetches more pages as needed.
  for await (const messageBatch of client.messages.batches.list({ limit: 20 })) {
    allMessageBatches.push(messageBatch);
  }
  return allMessageBatches;
}

또는 한 번에 한 페이지씩 요청할 수도 있어요:

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

// Convenience methods are provided for manually paginating:
while (page.hasNextPage()) {
  page = await page.getNextPage();
  // ...
}

기본 헤더 (Default headers)

SDK는 anthropic-version 헤더를 자동으로 2023-06-01로 보내요. 필요하다면 요청별로 기본 헤더를 설정해서 덮어쓸 수 있어요. 그렇게 하면 SDK에서 잘못된 타입이나 기타 예기치 않은 동작이 발생할 수 있다는 점을 인지하세요.

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" } }
);

고급 사용법 (Advanced usage)

원시 응답 데이터 접근(예: 헤더) (Accessing raw Response data)

모든 메서드가 반환하는 APIPromise 타입의 .asResponse() 메서드로 fetch()가 반환한 "원시" Response에 접근할 수 있어요. 이 메서드는 성공적인 응답의 헤더가 수신되는 즉시 반환하며 응답 본문을 소비하지 않으므로 커스텀 파싱이나 스트리밍 로직을 자유롭게 쓸 수 있어요.

.withResponse() 메서드로 원시 Response와 파싱된 데이터를 함께 얻을 수도 있어요. .asResponse()와 달리 이 메서드는 본문을 소비하고, 파싱된 후에 반환해요.

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

로깅 (Logging)

주의: 모든 로그 메시지는 디버깅 전용이에요. 로그 메시지의 형식과 내용은 릴리스 사이에 바뀔 수 있어요.

로그 레벨 (Log levels)

로그 레벨은 두 가지 방법으로 설정할 수 있어요:

1. ANTHROPIC_LOG 환경 변수
2. logLevel 클라이언트 옵션(설정하면 환경 변수를 덮어써요)

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

사용 가능한 로그 레벨(가장 장황한 것부터):

• 'debug' - 디버그 메시지, info, 경고, 에러 표시
• 'info' - info 메시지, 경고, 에러 표시
• 'warn' - 경고와 에러 표시(기본값)
• 'error' - 에러만 표시
• 'off' - 모든 로깅 비활성화

'debug' 레벨에서는 모든 HTTP 요청과 응답이 헤더와 본문을 포함해 로그로 남아요. 일부 인증 관련 헤더는 가려지지만 요청·응답 본문의 민감한 데이터는 여전히 보일 수 있어요.

커스텀 로거 (Custom logger)

기본적으로 이 라이브러리는 globalThis.console에 로그를 남겨요. 커스텀 로거도 제공할 수 있어요. pino, winston, bunyan, consola, signale, @std/log를 포함한 대부분의 로깅 라이브러리가 지원돼요. 로거가 작동하지 않으면 이슈를 열어 주세요. 커스텀 로거를 제공할 때 logLevel 옵션은 여전히 어떤 메시지가 방출되는지 제어하므로 설정한 레벨 아래의 메시지는 로거에 보내지지 않아요.

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
});

커스텀/문서화되지 않은 요청 만들기 (Making custom/undocumented requests)

이 라이브러리는 문서화된 API에 편리하게 접근하도록 타입화되어 있어요. 문서화되지 않은 엔드포인트, params, 응답 프로퍼티에 접근해야 한다면 여전히 라이브러리를 사용할 수 있어요.

문서화되지 않은 엔드포인트 (Undocumented endpoints)

문서화되지 않은 엔드포인트에 요청하려면 client.get, client.post 및 기타 HTTP 동사를 쓸 수 있어요. 재시도 같은 클라이언트의 옵션은 이런 요청을 만들 때 존중돼요.

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

문서화되지 않은 요청 파라미터 (Undocumented request parameters)

문서화되지 않은 파라미터로 요청하려면 문서화되지 않은 파라미터에 // @ts-expect-error를 쓸 수 있어요. 이 라이브러리는 런타임에 요청이 타입과 일치하는지 검증하지 않으므로 보낸 추가 값은 그대로 전송돼요.

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

GET 동사로 요청하면 추가 파라미터는 쿼리에 있고, 다른 모든 요청은 추가 파라미터를 본문에 보내요. 추가 인자를 명시적으로 보내려면 query, body, headers 요청 옵션으로 할 수 있어요.

문서화되지 않은 응답 프로퍼티 (Undocumented response properties)

문서화되지 않은 응답 프로퍼티에 접근하려면 응답 객체에 // @ts-expect-error를 쓰거나 응답 객체를 필요한 타입으로 캐스팅할 수 있어요. 요청 파라미터처럼 SDK는 API의 응답에서 추가 프로퍼티를 검증하거나 제거하지 않아요.

fetch 클라이언트 커스터마이징 (Customizing the fetch client)

기본적으로 이 라이브러리는 전역 fetch 함수가 정의되어 있다고 가정해요. 다른 fetch 함수를 쓰고 싶다면 전역을 폴리필하거나:

import fetch from "my-fetch";

globalThis.fetch = fetch;

클라이언트에 전달할 수 있어요:

import fetch from "my-fetch";

const client = new Anthropic({ fetch });

Fetch 옵션 (Fetch options)

fetch 함수를 덮어쓰지 않고 커스텀 fetch 옵션을 설정하려면 클라이언트를 만들거나 요청할 때 fetchOptions 객체를 제공할 수 있어요. (요청별 옵션이 클라이언트 옵션을 덮어써요.)

const client = new Anthropic({
  fetchOptions: {
    // `RequestInit` options
  }
});

프록시 설정 (Configuring proxies)

프록시 동작을 수정하려면 요청에 런타임별 프록시 옵션을 추가하는 커스텀 fetchOptions를 제공할 수 있어요:

<Node.js 경우>

import * as undici from "undici";

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

<Bun 경우>

const client = new Anthropic({
  fetchOptions: {
    proxy: "http://localhost:8888"
  }
});

<Deno 경우>

import Anthropic from "npm:@anthropic-ai/sdk";

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

베타 기능 (Beta features)

베타 기능은 일반 릴리스 전에 제공되어 조기 피드백을 받고 새 기능을 테스트해요. Claude의 모든 역량과 도구의 사용 가능 여부는 build with Claude 개요에서 확인할 수 있어요. 대부분의 베타 API 기능은 클라이언트의 beta 프로퍼티로 접근할 수 있어요. 특정 베타 기능을 활성화하려면 메시지를 만들 때 betas 필드에 적절한 베타 헤더를 추가해야 해요.

예를 들어 컨텍스트 편집을 활성화하려면:

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"]
});

런타임 지원 (Runtime support)

<브라우저 사용> dangerouslyAllowBrowser 옵션을 켜는 것은 클라이언트측 코드에서 비밀 API 자격 증명을 노출하므로 위험할 수 있어요. 웹 브라우저는 서버 환경보다 본질적으로 덜 안전하며, 브라우저에 접근할 수 있는 사용자는 누구나 이 자격 증명을 검사·추출·오용할 수 있어요. 이는 자격 증명을 사용한 무단 접근으로 이어지고 민감한 데이터나 기능을 손상시킬 수 있어요.

언제 위험하지 않을까요? 브라우저 지원을 켜도 큰 위험이 없을 수 있는 시나리오:

• 내부 도구: 애플리케이션이 신뢰할 수 있는 사용자만 있는 통제된 내부 환경에서만 쓰이면 자격 증명 노출 위험을 완화할 수 있어요.
• 개발 또는 디버깅 목적: 자격 증명이 단기적이고, 프로덕션 환경에서도 쓰이지 않거나, 자주 교체된다면 이 기능을 임시로 켜는 것이 허용될 수 있어요. </브라우저 사용>

플랫폼 통합 (Platform integrations)

참고: 코드 예시가 포함된 상세한 플랫폼 설정 가이드는 다음을 보세요:

• Amazon Bedrock
• Amazon Bedrock (Opus 4.6 and earlier)
• Claude Platform on AWS
• Google Cloud
• Microsoft Foundry

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를, Bedrock InvokeModel API를 쓰는 기존 애플리케이션에는 AnthropicBedrock을 쓰세요.

시맨틱 버저닝 (Semantic versioning)

이 패키지는 일반적으로 SemVer 규칙을 따르지만, 일부 하위 호환성이 깨지는 변경은 마이너 버전으로 릴리스될 수 있어요:

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

원활한 업그레이드 경험을 믿고 맡길 수 있도록 하위 호환성을 진지하게 여겨요.

자주 묻는 질문 (Frequently asked questions)

FAQ, 이슈, 커뮤니티 지원은 GitHub 저장소를 보세요.

추가 자료 (Additional resources)

• GitHub 저장소
• API 참조
• 메시지 스트리밍
• Claude와 함께하는 도구 사용

더 알아보기 (Learn more)

• API 개요
• Python SDK
• Go SDK
• 메시지 스트리밍