TypeScript SDK API

query() — 주요 진입점

query()는 TypeScript SDK의 핵심 함수입니다. 프롬프트를 전송하고 스트리밍 응답을 비동기 이터레이터로 받습니다.

import { query, type SDKMessage } from '@anthropic-ai/claude-code';

async function main() {
  const messages: SDKMessage[] = [];

  for await (const message of query({
    prompt: '이 코드베이스의 아키텍처를 설명해 주세요',
    options: {
      model: 'claude-sonnet-4-5',
      maxTurns: 5,
      systemPrompt: '당신은 시니어 소프트웨어 아키텍트입니다.',
      cwd: '/path/to/project',
      permissionMode: 'auto-edit',
    }
  })) {
    messages.push(message);

    if (message.type === 'assistant') {
      process.stdout.write(message.message.content as string);
    }

    if (message.type === 'result') {
      console.log(`\n비용: $${message.cost_usd}`);
      console.log(`소요 시간: ${message.duration_ms}ms`);
    }
  }
}

옵션	타입	설명
model	string	사용할 Claude 모델
maxTurns	number	최대 대화 턴 수
systemPrompt	string	시스템 프롬프트 (기존 교체)
appendSystemPrompt	string	기존 시스템 프롬프트에 추가
cwd	string	작업 디렉토리 경로
permissionMode	string	권한 모드 설정

세션 관리 API

import {
  listSessions,
  getSessionMessages,
  forkSession,
  renameSession,
  tagSession
} from '@anthropic-ai/claude-code';

// 세션 목록 조회 (태그 필터링)
const sessions = await listSessions({ tags: ['production'] });

// 세션 메시지 조회
const history = await getSessionMessages(sessions[0].id);

// 세션 포크 (분기점 생성)
const forkedId = await forkSession(sessions[0].id, {
  afterMessageId: history[5].uuid
});

// 이름과 태그 관리
await renameSession(forkedId, '결제 모듈 리팩토링 실험');
await tagSession(forkedId, ['experiment', 'payment', '2025-q1']);

커스텀 에이전트 정의

에이전트를 JSON으로 정의하여 SDK에 등록할 수 있습니다.

const agents = [
  {
    name: 'security-reviewer',
    description: '보안 취약점을 분석하는 전문 에이전트',
    model: 'claude-opus-4-5',
    systemPrompt: '당신은 보안 전문가입니다. OWASP Top 10을 기준으로 분석합니다.',
    tools: ['Read', 'Bash(grep:*)', 'Bash(find:*)'],
    maxTurns: 10
  },
  {
    name: 'test-writer',
    description: '단위 테스트를 작성하는 에이전트',
    model: 'claude-haiku-4-5',
    tools: ['Read', 'Write', 'Edit'],
    maxTurns: 20
  }
];

for await (const message of query({
  prompt: '인증 모듈의 보안을 검토해 주세요',
  options: { agents }
})) {
  // ...
}

SDK 훅 등록

SDK를 통해 훅 콜백을 프로그래매틱으로 등록할 수 있습니다.

import { query, type HookCallback } from '@anthropic-ai/claude-code';

const preToolUseHook: HookCallback = async (event) => {
  if (event.tool === 'Bash' && event.input.command.includes('rm')) {
    console.warn('위험한 명령어 감지:', event.input.command);
    return { block: true, message: '이 명령어는 허용되지 않습니다' };
  }
  return { block: false };
};

for await (const message of query({
  prompt: '코드를 정리해 주세요',
  options: {
    hookCallbackIds: {
      PreToolUse: preToolUseHook
    }
  }
})) {
  // ...
}

sdkMcpServers

인프로세스 MCP 서버를 SDK 세션에 직접 연결합니다.

import { query } from '@anthropic-ai/claude-code';
import { MyDatabaseServer } from './mcp-servers/database';

for await (const message of query({
  prompt: '사용자 테이블의 스키마를 설명해 주세요',
  options: {
    sdkMcpServers: [
      {
        name: 'database',
        server: new MyDatabaseServer({ connectionString: process.env.DB_URL })
      }
    ]
  }
})) {
  // ...
}

sdkMcpServers를 사용하면 설정 파일 없이 코드에서 직접 MCP 서버를 주입할 수 있어 테스트와 동적 구성에 유용합니다. 현재 API는 @alpha 상태이므로 프로덕션 사용 시 버전을 고정하는 것을 권장합니다.