Quick Comparison

Agent SDK는 Claude Code의 agent loop, tools, context 관리를 TypeScript 또는 Python 프로그램 안에서 쓰는 라이브러리입니다. 한 번의 shell 자동화는 claude -p, 앱 안에서 도구 호출·중간 결과·세션을 제어해야 하면 Agent SDK, 모델 API를 직접 호출하고 agent loop까지 직접 만들려면 Client SDK를 고릅니다.

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

for await (const message of query({
  prompt: "Find error-handling gaps and report them without editing files.",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
    permissionMode: "dontAsk",
    maxTurns: 5,
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

실행 모델과 인증

Agent SDK는 Claude Code의 도구, agent loop, context 관리를 로컬 프로세스에서 사용합니다. TypeScript 패키지는 @anthropic-ai/claude-agent-sdk, Python 패키지는 claude-agent-sdk입니다. 다른 언어에서는 SDK 대신 claude -p --output-format json 같은 CLI subprocess를 사용합니다.

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

제품 사용자에게 Agent SDK를 제공할 때 Claude.ai 로그인이나 구독 rate limit을 대신 제공할 수는 없습니다. API key 기반 인증을 사용하고, key는 repository나 prompt에 넣지 말고 server-side secret 또는 환경 변수로 주입합니다. 누가 비용을 부담하고, 어느 사용자 요청이 어느 agent 실행과 연결되는지도 제품 쪽에서 기록해야 합니다.

권한을 정하는 방법

allowedTools는 허용 목록처럼 도구를 감추는 설정이 아니라, 나열한 도구의 승인 절차를 자동 통과시키는 설정입니다. 목록에 없는 도구는 여전히 일반 permission 결정으로 갑니다. 읽기 전용 agent를 실제로 읽기 도구로만 제한하려면 allowedTools와 permissionMode: "dontAsk"를 함께 사용합니다. dontAsk는 사전 허용되지 않은 도구를 사용자에게 묻지 않고 거부합니다.

const readOnly = {
  allowedTools: ["Read", "Glob", "Grep"],
  permissionMode: "dontAsk",
};

const editWithReview = {
  allowedTools: ["Read", "Glob", "Grep"],
  // Edit와 Bash는 자동 승인하지 않는다.
  // 승인 callback 또는 사용자 승인을 거치게 둔다.
};

bypassPermissions는 사용자 확인을 우회하므로 일반 자동화의 기본값으로 쓰지 않습니다. 명시적으로 막을 도구가 있다면 disallowedTools를 추가하고, 입력값·경로·명령 내용처럼 매 호출마다 확인할 규칙은 PreToolUse hook 또는 canUseTool callback으로 검증합니다. callback은 이미 다른 permission 규칙으로 결정되지 않은 요청에만 도달할 수 있습니다.

결과와 실패 처리

query()는 최종 문장 하나가 아니라 메시지 stream을 돌려줍니다. 화면에 진행 상황을 보일지, 도구 호출을 감사 로그로 남길지, result message만 사용자에게 보일지를 호출자가 정합니다. 실행 전에 최대 turn, timeout, 취소, 재시도 가능한 오류, 부분 결과의 처리 규칙을 정합니다.

사용자 요청
  -> query()와 도구·권한 설정
  -> stream의 진행·tool message 기록
  -> result / error / 취소를 각 정책으로 처리

자주 틀리는 부분

• allowedTools만 쓰고 읽기 전용이라고 가정하지 않습니다. 다른 도구는 prompt, permission mode, callback에 따라 여전히 요청될 수 있습니다.
• async 작업의 완료·예외·취소를 결과 문자열 하나로 처리하지 않습니다. 호출 task와 stream 종료 상태를 함께 관찰합니다.
• 자동 수정 agent의 성공을 agent의 답변만으로 판정하지 않습니다. 변경 범위에 맞는 test, build, 실행 검증, diff 검토를 별도 단계로 둡니다.