핵심 정리

Agent SDK
  -> TypeScript / Python에서 query 호출
  -> built-in tools와 permissions 지정
  -> session, errors, streaming 결과를 코드로 처리

CLI headless
  -> claude -p 로 한 번 실행
  -> shell script에 붙이기 쉬움

사용 흐름

Agent SDK는 Claude Code의 agent harness를 코드에서 쓰는 표면이다

Agent SDK는 터미널에서 claude -p를 호출하는 수준을 넘어, 애플리케이션 코드 안에서 Claude 기반 agent를 구성하는 표면입니다. TypeScript와 Python에서 query를 호출하고, prompt, working directory, allowed tools, permission mode, MCP 연결 같은 실행 조건을 코드로 관리합니다.

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Find suspicious error handling in this repository",
  options: {
    allowedTools: ["Read", "Grep", "Glob"]
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

단순 요약이나 일회성 분석은 CLI headless가 더 가볍고, 제품 기능이나 반복 서비스에 넣을 agent는 SDK가 더 적합합니다.

설치와 인증은 실행 환경의 일부로 관리해야 한다

공식 문서 기준으로 TypeScript 패키지는 @anthropic-ai/claude-agent-sdk, Python 패키지는 claude-agent-sdk를 사용합니다. API 인증은 ANTHROPIC_API_KEY 같은 환경 변수로 설정합니다.

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

CI, 사내 도구, 서버 환경에서 사용할 때는 API key를 코드나 repository에 넣지 말고 secret manager나 환경 변수로 주입해야 합니다. 로컬 Claude Code 로그인 상태에 의존하는 도구로 설계하면 배포 환경에서 재현성이 떨어집니다.

allowedTools는 agent가 할 수 있는 일을 먼저 제한한다

SDK agent는 파일 읽기, 검색, 명령 실행, 편집 같은 도구를 사용할 수 있습니다. 그래서 prompt보다 먼저 "이 agent가 어떤 도구를 써도 되는가"를 정해야 합니다. 읽기 전용 리뷰 agent라면 Read, Grep, Glob 중심으로 제한하고, 코드 수정 agent라면 Edit이나 Bash를 추가하되 실행 범위를 좁혀야 합니다.

const options = {
  allowedTools: ["Read", "Grep", "Glob"],
  maxTurns: 5
};

도구 권한이 넓은 agent는 더 많은 일을 할 수 있지만, 실패했을 때 영향 범위도 넓어집니다. 운영 자동화에서는 기본을 읽기 전용으로 두고, 수정이나 명령 실행은 별도 승인 흐름으로 분리하는 것이 안전합니다.

streaming 결과와 실패 처리를 설계해야 한다

SDK는 메시지를 streaming 형태로 받을 수 있습니다. 따라서 최종 결과만 볼 것인지, 중간 tool use와 progress를 기록할 것인지, 실패 시 재시도할 것인지를 애플리케이션 쪽에서 설계해야 합니다.

query()
  -> message stream
  -> result message 확인
  -> 실패, timeout, rate limit 처리
  -> 로그와 감사 기록 저장

Agent를 제품 기능으로 넣는다면 timeout, retry, rate limit, 사용자 취소, partial result 처리까지 함께 봐야 합니다.

선택 기준

주의할 점

자동 수정 agent를 만들 때는 "성공 기준"을 코드로 검증할 수 있어야 합니다. 테스트, 타입체크, lint, diff 검토 없이 agent 결과만 신뢰하면 변경이 누적될수록 원인 추적이 어려워집니다.