CLI, SDK 및 라이브러리클라이언트 SDK

TypeScript SDK

Node.js, Deno, Bun 및 브라우저 환경을 위한 Anthropic TypeScript SDK 설치 및 구성

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

코드 예제가 포함된 API 기능 문서는 API 레퍼런스를 참조하세요. 이 페이지는 TypeScript 전용 SDK 기능 및 구성을 다룹니다.

설치

npm install @anthropic-ai/sdk

요구 사항

TypeScript >= 4.9가 지원됩니다.

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

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에서 이슈를 열거나 추천해 주세요.

사용법

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

console.log(message.content);

Workload Identity Federation을 포함한 인증 옵션에 대해서는 인증을 참조하세요.

요청 및 응답 타입

이 라이브러리에는 모든 요청 매개변수와 응답 필드에 대한 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-4-8"
};
const message: Anthropic.Message = await client.messages.create(params);

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

토큰 계산

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

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

스트리밍 응답

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

const client = new Anthropic();

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

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

스트리밍 헬퍼

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

const anthropic = new Anthropic();

const stream = anthropic.messages
  .stream({
    model: "claude-opus-4-8",
    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 스키마를 사용하여 도구의 입력을 설명할 수 있습니다. 그런 다음 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-4-8",
  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는 콘텐츠 블록을 허용하므로 오류 응답에 이미지나 기타 구조화된 콘텐츠를 포함할 수 있습니다:

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는 함수 호출이라고도 하는 도구 사용을 지원합니다. 자세한 내용은 Claude의 도구 사용을 참조하세요.

MCP 헬퍼

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

// 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-4-8",
  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-4-8",
  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-4-8",
  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.beta.files.upload({ file: mcpResourceToFile(fileResource) });

MCP 오류 처리

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

메시지 배치

이 SDK는 client.messages.batches 네임스페이스에서 Message Batches API를 지원합니다.

배치 생성

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

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

배치에서 결과 가져오기

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(또는 동일한 구조의 객체)
fetch Response(또는 동일한 구조의 객체)
fs.ReadStream
toFile 헬퍼의 반환 값

files API는 content-type을 자동으로 추론하지 않으므로 명시적으로 설정하세요:

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

const client = new Anthropic();

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

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

// 또는 `Buffer` / `Uint8Array`를 전달할 수 있습니다
await client.beta.files.upload({
  file: await toFile(Buffer.from("my bytes"), "file", { type: "text/plain" })
});
await client.beta.files.upload({
  file: await toFile(new Uint8Array([0, 1, 2]), "file", { type: "text/plain" })
});

오류 처리

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

const message = await client.messages
  .create({
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-4-8"
  })
  .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를 참조하세요.

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

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

재시도

특정 오류는 기본적으로 짧은 지수 백오프와 함께 자동으로 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-4-8"
  },
  { maxRetries: 5 }
);

타임아웃

기본적으로 요청은 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-4-8"
  },
  { timeout: 5 * 1000 }
);

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

타임아웃된 요청은 기본적으로 두 번 재시도됩니다.

장시간 요청

더 오래 실행되는 요청에는 스트리밍 Messages API 사용을 고려하세요.

스트리밍을 사용하지 않고 큰 max_tokens 값을 설정하는 것은 피하세요. 일부 네트워크는 일정 시간 후 유휴 연결을 끊을 수 있으며, 이로 인해 Anthropic으로부터 응답을 받지 못한 채 요청이 실패하거나 타임아웃될 수 있습니다.

이 SDK는 스트리밍이 아닌 요청이 대략 10분 이상 걸릴 것으로 예상되는 경우에도 오류를 throw합니다. stream: true를 전달하거나 클라이언트 또는 요청 수준에서 timeout 옵션을 재정의하면 이 오류가 비활성화됩니다.

스트리밍이 아닌 요청의 예상 요청 지연 시간이 타임아웃보다 긴 경우 클라이언트는 응답을 받지 못한 채 연결을 종료하고 재시도합니다.

fetch 구현에서 지원하는 경우, SDK는 일부 네트워크에서 유휴 연결 타임아웃의 영향을 줄이기 위해 TCP 소켓 keep-alive 옵션을 설정합니다. 이는 사용자 지정 프록시를 구성하여 재정의할 수 있습니다.

자동 페이지네이션

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

async function fetchAllMessageBatches() {
  const allMessageBatches = [];
  // 필요에 따라 추가 페이지를 자동으로 가져옵니다.
  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);
}

// 수동으로 페이지를 이동하기 위한 편의 메서드가 제공됩니다:
while (page.hasNextPage()) {
  page = await page.getNextPage();
  // ...
}

기본 헤더

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-4-8"
  },
  { headers: { "anthropic-version": "My-Custom-Value" } }
);

고급 사용법

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

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

.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-4-8"
  })
  .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-4-8"
  })
  .withResponse();
console.log(raw.headers.get("X-My-Header"));
console.log(message.content);

로깅

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

로그 레벨

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

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

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

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

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

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

사용자 지정 로거

기본적으로 이 라이브러리는 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
});

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

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

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

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

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

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

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

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 함수를 사용하려면 전역을 폴리필할 수 있습니다:

import fetch from "my-fetch";

globalThis.fetch = fetch;

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

import fetch from "my-fetch";

const client = new Anthropic({ fetch });

Fetch 옵션

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

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

프록시 구성

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

베타 기능

베타 기능은 조기 피드백을 받고 새로운 기능을 테스트하기 위해 정식 출시 전에 제공됩니다. Claude의 모든 기능 및 도구의 가용성은 Claude로 빌드하기 개요에서 확인할 수 있습니다.

클라이언트의 beta 속성을 통해 대부분의 베타 API 기능에 접근할 수 있습니다. 특정 베타 기능을 활성화하려면 메시지를 생성할 때 betas 필드에 적절한 베타 헤더를 추가해야 합니다.

예를 들어, Files API를 사용하려면:

const client = new Anthropic();
const response = await client.beta.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "Please summarize this document for me." },
        {
          type: "document",
          source: {
            type: "file",
            file_id: "file_abc123"
          }
        }
      ]
    }
  ],
  betas: ["files-api-2025-04-14"]
});

런타임 지원

플랫폼 통합

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

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

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

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

시맨틱 버저닝

이 패키지는 일반적으로 SemVer 규칙을 따르지만, 특정 하위 호환성이 없는 변경 사항은 마이너 버전으로 릴리스될 수 있습니다:

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

원활한 업그레이드 경험을 보장하기 위해 하위 호환성을 중요하게 고려합니다.

자주 묻는 질문

FAQ, 이슈 및 커뮤니티 지원은 GitHub 저장소를 참조하세요.

추가 리소스

Was this page helpful?

CLI, SDK 및 라이브러리클라이언트 SDK

TypeScript SDK

Node.js, Deno, Bun 및 브라우저 환경을 위한 Anthropic TypeScript SDK 설치 및 구성

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

코드 예제가 포함된 API 기능 문서는 API 레퍼런스를 참조하세요. 이 페이지는 TypeScript 전용 SDK 기능 및 구성을 다룹니다.

설치

npm install @anthropic-ai/sdk

요구 사항

TypeScript >= 4.9가 지원됩니다.

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

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에서 이슈를 열거나 추천해 주세요.

사용법

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

console.log(message.content);

Workload Identity Federation을 포함한 인증 옵션에 대해서는 인증을 참조하세요.

요청 및 응답 타입

이 라이브러리에는 모든 요청 매개변수와 응답 필드에 대한 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-4-8"
};
const message: Anthropic.Message = await client.messages.create(params);

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

토큰 계산

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

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

스트리밍 응답

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

const client = new Anthropic();

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

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

스트리밍 헬퍼

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

const anthropic = new Anthropic();

const stream = anthropic.messages
  .stream({
    model: "claude-opus-4-8",
    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(...)을 사용한 스트리밍은 이벤트 핸들러 및 누적을 포함한 다양한 편의 헬퍼를 제공합니다.

도구 헬퍼

도구 사용에 대한 자세한 내용은 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-4-8",
  max_tokens: 1000,
  messages: [{ role: "user", content: "What is the weather in San Francisco?" }],
  tools: [weatherTool]
});

console.log(finalMessage.content);

도구 오류

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는 함수 호출이라고도 하는 도구 사용을 지원합니다. 자세한 내용은 Claude의 도구 사용을 참조하세요.

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

// 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-4-8",
  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-4-8",
  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-4-8",
  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.beta.files.upload({ file: mcpResourceToFile(fileResource) });

MCP 오류 처리

메시지 배치

이 SDK는 client.messages.batches 네임스페이스에서 Message Batches API를 지원합니다.

배치 생성

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

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

배치에서 결과 가져오기

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(또는 동일한 구조의 객체)
fetch Response(또는 동일한 구조의 객체)
fs.ReadStream
toFile 헬퍼의 반환 값

files API는 content-type을 자동으로 추론하지 않으므로 명시적으로 설정하세요:

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

const client = new Anthropic();

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

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

// 또는 `Buffer` / `Uint8Array`를 전달할 수 있습니다
await client.beta.files.upload({
  file: await toFile(Buffer.from("my bytes"), "file", { type: "text/plain" })
});
await client.beta.files.upload({
  file: await toFile(new Uint8Array([0, 1, 2]), "file", { type: "text/plain" })
});

오류 처리

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

const message = await client.messages
  .create({
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-4-8"
  })
  .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를 참조하세요.

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

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

재시도

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-4-8"
  },
  { maxRetries: 5 }
);

타임아웃

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-4-8"
  },
  { timeout: 5 * 1000 }
);

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

타임아웃된 요청은 기본적으로 두 번 재시도됩니다.

장시간 요청

더 오래 실행되는 요청에는 스트리밍 Messages API 사용을 고려하세요.

스트리밍이 아닌 요청의 예상 요청 지연 시간이 타임아웃보다 긴 경우 클라이언트는 응답을 받지 못한 채 연결을 종료하고 재시도합니다.

자동 페이지네이션

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

async function fetchAllMessageBatches() {
  const allMessageBatches = [];
  // 필요에 따라 추가 페이지를 자동으로 가져옵니다.
  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);
}

// 수동으로 페이지를 이동하기 위한 편의 메서드가 제공됩니다:
while (page.hasNextPage()) {
  page = await page.getNextPage();
  // ...
}

기본 헤더

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-4-8"
  },
  { headers: { "anthropic-version": "My-Custom-Value" } }
);

고급 사용법

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

const client = new Anthropic();

const response = await client.messages
  .create({
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-4-8"
  })
  .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-4-8"
  })
  .withResponse();
console.log(raw.headers.get("X-My-Header"));
console.log(message.content);

로깅

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

로그 레벨

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

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

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

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

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

사용자 지정 로거

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

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

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

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

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

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

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

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

문서화되지 않은 응답 속성

fetch 클라이언트 사용자 지정

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

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

import fetch from "my-fetch";

globalThis.fetch = fetch;

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

import fetch from "my-fetch";

const client = new Anthropic({ fetch });

Fetch 옵션

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

프록시 구성

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

베타 기능

예를 들어, Files API를 사용하려면:

const client = new Anthropic();
const response = await client.beta.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "Please summarize this document for me." },
        {
          type: "document",
          source: {
            type: "file",
            file_id: "file_abc123"
          }
        }
      ]
    }
  ],
  betas: ["files-api-2025-04-14"]
});

런타임 지원

플랫폼 통합

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

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

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

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

시맨틱 버저닝

이 패키지는 일반적으로 SemVer 규칙을 따르지만, 특정 하위 호환성이 없는 변경 사항은 마이너 버전으로 릴리스될 수 있습니다:

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

원활한 업그레이드 경험을 보장하기 위해 하위 호환성을 중요하게 고려합니다.

자주 묻는 질문

FAQ, 이슈 및 커뮤니티 지원은 GitHub 저장소를 참조하세요.

추가 리소스

Was this page helpful?

설치

요구 사항

사용법

요청 및 응답 타입

토큰 계산

스트리밍 응답

스트리밍 헬퍼

도구 헬퍼

도구 오류

도구 사용

MCP 헬퍼

MCP 오류 처리

메시지 배치

배치 생성

배치에서 결과 가져오기

파일 업로드

오류 처리

요청 ID

재시도

타임아웃

장시간 요청

자동 페이지네이션

기본 헤더

고급 사용법

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

로깅

로그 레벨

사용자 지정 로거

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

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

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

문서화되지 않은 응답 속성

fetch 클라이언트 사용자 지정

Fetch 옵션

프록시 구성

베타 기능

런타임 지원

브라우저 사용

플랫폼 통합

시맨틱 버저닝

자주 묻는 질문

추가 리소스

설치

요구 사항

사용법

요청 및 응답 타입

토큰 계산

스트리밍 응답

스트리밍 헬퍼

도구 헬퍼

도구 오류

도구 사용

MCP 헬퍼

MCP 오류 처리

메시지 배치

배치 생성

배치에서 결과 가져오기

파일 업로드

오류 처리

요청 ID

재시도

타임아웃

장시간 요청

자동 페이지네이션

기본 헤더

고급 사용법

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

로깅

로그 레벨

사용자 지정 로거

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

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

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

문서화되지 않은 응답 속성

fetch 클라이언트 사용자 지정

Fetch 옵션

프록시 구성

베타 기능

런타임 지원

브라우저 사용