Claude Agent SDK 간단 정리: Claude Code를 서비스로 만들기

Claude Agent SDK는 Claude Code의 에이전트 기능을 TypeScript나 Python 애플리케이션 안에서 사용할 수 있게 해주는 SDK다.

CLI에서 사용하던 파일 읽기, 수정, 도구 호출, 권한, 훅, 세션 기능을 그대로 가져와 웹 서비스나 사내 자동화 에이전트로 만들 수 있다.

1. 기본 사용법

TypeScript에서는 query() 하나로 에이전트 루프를 실행한다.

npm install @anthropic-ai/claude-agent-sdk

import { query } from "@anthropic-ai/claude-agent-sdk";
 
for await (const message of query({
  prompt: "utils.py의 버그를 찾아 수정해",
  options: {
    allowedTools: ["Read", "Edit", "Glob"],
    permissionMode: "acceptEdits",
    maxTurns: 10,
  },
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

SDK가 다음 과정을 알아서 반복한다.

생각 → 도구 호출 → 결과 확인 → 다음 행동 결정

개발자는 메시지 스트림을 받아 화면에 보여주거나 최종 결과만 처리하면 된다.

2. 커스텀 도구 연결

SDK 내부에 직접 MCP 도구를 만들 수도 있다.

도구는 다음 네 가지로 구성된다.

• 이름
• 설명
• 입력 스키마
• 실행 핸들러

const searchWiki = tool(
  "search_wiki",
  "사내 위키에서 관련 문서를 검색한다",
  {
    query: z.string(),
    limit: z.number().default(5),
  },
  async ({ query, limit }) => {
    const result = await wiki.search(query, limit);
 
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result),
        },
      ],
    };
  },
);

애플리케이션에서만 사용하는 DB 조회나 사내 로직은 인프로세스 도구로 만들고, 여러 서비스에서 공유해야 한다면 별도의 MCP 서버로 분리하는 방식이 적합하다.

도구 실행에 실패했을 때는 예외를 그대로 던지기보다 isError: true로 반환하는 것이 중요하다. 그래야 전체 에이전트가 종료되지 않고 Claude가 재시도하거나 다른 방법을 선택할 수 있다.

3. 구조화된 결과 받기

에이전트 응답을 문자열로 받아 다시 파싱할 필요도 없다.

Zod나 Pydantic으로 출력 스키마를 정의하면 검증된 JSON 결과를 받을 수 있다.

const Answer = z.object({
  answer: z.string(),
  sources: z.array(z.string()),
  confidence: z.enum(["low", "medium", "high"]),
});
 
const options = {
  outputFormat: {
    type: "json_schema",
    schema: z.toJSONSchema(Answer),
  },
};

에이전트가 여러 도구를 사용하며 자유롭게 조사하더라도 최종 결과는 정해진 스키마에 맞춰 반환된다.

스키마는 처음부터 너무 복잡하게 만들지 말고, 없을 수 있는 필드는 선택값으로 정의하는 것이 좋다.

4. 권한과 훅

에이전트는 실제 파일과 명령어를 다루기 때문에 권한 통제가 중요하다.

주요 통제 방법은 다음과 같다.

• tools: 에이전트에게 노출할 도구 제한
• allowedTools: 자동 실행을 허용할 도구
• disallowedTools: 실행을 금지할 도구
• canUseTool: 호출마다 승인 여부 판단
• hooks: 도구 실행 전후 감사, 차단 및 후처리

가능하면 필요한 도구만 노출하고, 무인 환경에서는 dontAsk와 명확한 허용 목록을 함께 사용하는 것이 안전하다.

bypassPermissions는 모든 도구를 확인 없이 실행하므로 격리된 CI나 샌드박스 환경으로 제한해야 한다.

5. 세션과 상태 관리

최종 결과에는 session_id가 포함된다. 이를 저장하면 다음 요청에서 이전 대화를 이어갈 수 있다.

options: {
  resume: sessionId,
}

다만 기본 세션 데이터는 로컬에 저장된다. 여러 서버나 Kubernetes 환경에서 운영한다면 세션 데이터를 S3, Redis 같은 외부 저장소에 보관해야 한다.

비용도 결과 메시지에서 확인할 수 있다.

• 토큰 사용량
• 실행 턴 수
• 총비용
• 세션 ID

운영 환경에서는 사용자나 테넌트별 비용과 실패율을 기록하는 것이 좋다.

6. 프로덕션 운영 시 고려사항

Claude Agent SDK의 query()는 내부적으로 Claude Code 프로세스를 실행한다. 일반적인 짧은 API 요청보다는 작업 시간이 긴 백그라운드 잡에 가깝다.

따라서 서비스로 운영할 때는 다음 구조가 자연스럽다.

API 요청 → 작업 큐 → 에이전트 워커 → 결과 저장 → 폴링 또는 알림

Kubernetes에서는 다음 항목을 챙겨야 한다.

• 비루트 컨테이너 실행
• CPU·메모리 제한 설정
• maxTurns로 무한 실행 방지
• IRSA 또는 Pod Identity 사용
• 세션 외부 저장
• OpenTelemetry 기반 관측
• 테넌트별 작업 디렉터리와 자격 증명 분리
• 외부 네트워크 접근 제한

정리

Claude Agent SDK의 핵심은 Claude에게 단순히 질문을 보내는 것이 아니다.

query + 도구 + 출력 스키마 + 권한 + 세션

이 다섯 가지를 조합해 실제 업무를 수행하는 에이전트 서비스를 만드는 것이 목적이다.

개인 스크립트나 단순 CI 자동화라면 Claude Code의 헤드리스 모드로도 충분하다. 반면 사내 위키 검색, PR 리뷰, 장애 분석처럼 API·세션·사용자별 권한·비용 추적이 필요하다면 Agent SDK가 더 적합하다.

처음에는 읽기 전용 도구 하나와 단순한 출력 스키마로 시작하고, 이후 세션과 작업 큐, 관측 기능을 붙이는 순서가 현실적이다.