Claude Code Agent SDK 입문 ― 자율 에이전트를 빠르게 구축하는 방법

Agent SDK란 무엇인가

Claude Code Agent SDK는 Claude 모델을 코어로 삼아 자율형 에이전트를 프로그래밍 방식으로 구축하기 위한 프레임워크입니다. 단순한 API 호출과 달리, 에이전트는 목표를 받으면 스스로 도구를 선택하고 결과를 평가하며 멀티스텝 추론 루프를 실행합니다.

기존 챗봇은 “질문→답변”의 1회 왕복으로 완결되었지만, Agent SDK를 사용하면 “파일 읽기→문제 식별→수정 적용→테스트 실행→결과 보고”와 같은 복잡한 워크플로우를 한 번의 지시로 완료할 수 있습니다.

설정

프로젝트를 초기화하고 SDK를 설치합니다.

mkdir my-agent && cd my-agent
npm init -y
npm install @anthropic-ai/claude-code --save

TypeScript로 개발하는 경우 타입 정의도 추가합니다.

npm install typescript @types/node --save-dev
npx tsc --init

환경 변수에 ANTHROPIC_API_KEY를 설정하면 준비 완료입니다.

export ANTHROPIC_API_KEY="sk-ant-..."

최소 구성의 에이전트

파일 시스템을 조작할 수 있는 간단한 에이전트 예시입니다.

import { Claude } from "@anthropic-ai/claude-code";

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  maxTurns: 10,
});

async function main() {
  const result = await agent.run(
    "src 디렉터리 내의 TODO 코멘트를 목록화하고 우선순위순으로 정렬해주세요"
  );
  console.log(result.text);
}

main();

maxTurns는 에이전트가 실행할 수 있는 최대 스텝 수입니다. 무한 루프를 방지하는 안전장치로 반드시 설정하세요.

커스텀 도구 정의

Agent SDK의 진가는 커스텀 도구를 정의할 수 있다는 점입니다. 에이전트에 외부 API나 데이터베이스 접근 권한을 부여하면 더욱 실용적인 자동화가 가능합니다.

import { Claude, Tool } from "@anthropic-ai/claude-code";

const fetchIssueTool: Tool = {
  name: "fetch_github_issue",
  description: "GitHub Issue를 가져온다",
  parameters: {
    type: "object",
    properties: {
      owner: { type: "string", description: "저장소 소유자" },
      repo: { type: "string", description: "저장소 이름" },
      number: { type: "number", description: "Issue 번호" },
    },
    required: ["owner", "repo", "number"],
  },
  async execute({ owner, repo, number }) {
    const res = await fetch(
      `https://api.github.com/repos/${owner}/${repo}/issues/${number}`,
      { headers: { Authorization: `token ${process.env.GITHUB_TOKEN}` } }
    );
    return await res.json();
  },
};

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  tools: [fetchIssueTool],
  maxTurns: 15,
});

이렇게 정의하면 에이전트는 필요에 따라 fetch_github_issue를 호출하고, 가져온 정보를 바탕으로 다음 행동을 결정합니다.

멀티스텝 실행 흐름

Agent SDK의 에이전트는 내부적으로 다음 루프를 실행합니다.

1. 계획(Planning) ― 사용자 지시를 분해하여 필요한 스텝을 파악
2. 도구 선택(Tool Selection) ― 사용 가능한 도구 중 최적의 것을 선택
3. 실행(Execution) ― 도구를 실행하고 결과를 취득
4. 평가(Evaluation) ― 결과를 확인하고 목표 달성 여부를 판정
5. 반복 또는 완료 ― 미달성이면 1로 돌아가고, 달성이면 최종 답변을 생성

이 루프 덕분에 모든 절차를 사전에 하드코딩할 필요 없이 상황에 맞는 유연한 처리가 가능합니다.

실전: PR 리뷰 자동화 에이전트

실제 사용 사례로 Pull Request 자동 리뷰 에이전트를 구축해봅시다.

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  tools: [fetchIssueTool, readFileTool, postCommentTool],
  maxTurns: 20,
  systemPrompt: `당신은 코드 리뷰 전문가입니다.
PR의 diff를 읽고 다음 관점에서 리뷰해주세요:
- 버그 가능성
- 보안 리스크
- 성능 문제
- 개선 제안`,
});

const result = await agent.run(
  "PR #42를 리뷰하고, 문제가 있으면 코멘트를 남겨주세요"
);

systemPrompt로 에이전트의 역할과 판단 기준을 명시하면 일관성 있는 리뷰를 실현할 수 있습니다.

에러 핸들링과 재시도

프로덕션 환경에서는 견고한 에러 핸들링이 필수적입니다.

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  maxTurns: 10,
  onError: (error, context) => {
    console.error(`스텝 ${context.turn}에서 에러:`, error.message);
    if (context.turn >= 3) {
      return "abort"; // 3회 실패 시 중단
    }
    return "retry"; // 그 외에는 재시도
  },
});

정리 및 다음 단계

Agent SDK를 사용하면 단발성 AI 응답이 아닌 여러 스텝에 걸친 복잡한 태스크를 자동화할 수 있습니다. 먼저 작은 태스크(파일 정리나 로그 분석 등)부터 시작하고, 점차 도구를 추가하여 에이전트의 능력을 확장해나가는 것을 추천합니다.

Claude Code의 기본 사용법은 입문 가이드를, API를 활용한 개발 방법은 API 개발 가이드를 참고해주세요. CLI 도구 연동은 CLI 도구 개발이 도움이 됩니다.

더 자세한 정보는 Anthropic 공식 문서와 Claude Code GitHub 저장소를 확인하세요.