Claude Agent SDK로 코딩 에이전트 만들기 — query() 한 줄이면 파일까지 만진다

LLM에 도구를 붙여서 "에이전트"를 만들려면 보통 이런 루프를 손으로 짠다. 모델 호출 → tool_use 블록 감지 → 도구 실행 → 결과 다시 넣기 → 모델이 멈출 때까지 반복. 몇 번 짜보면 알겠지만, 에이전트 자체보다 이 루프랑 파일 읽기/쓰기 도구를 구현하는 데 시간이 더 든다.

그러다 Claude Agent SDK를 알게 됐다. Claude Code를 라이브러리로 떼어낸 물건인데, 파일 읽기·쓰기·편집·bash·grep 같은 도구가 이미 다 들어있고 에이전트 루프도 SDK가 돌려준다. 나는 프롬프트랑 옵션만 넘기면 된다.

Anthropic API 툴 러너랑은 다르다

처음엔 API SDK에 있는 툴 러너(client.beta.messages.tool_runner)랑 헷갈렸다. 이름이 비슷한데 역할이 다르다. 툴 러너는 내가 정의한 도구만 루프 돌려준다. 내장 도구도, 파일시스템 접근도 없다. Agent SDK는 반대로 Read/Write/Edit/Bash/Grep 같은 도구가 처음부터 딸려 온다. "코드베이스를 만지는 에이전트"가 목표라면 Agent SDK 쪽이다.

설치하고 돌려보기

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

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

const result = query({
  prompt: 'src/utils 폴더의 함수들에 JSDoc 주석을 달아줘',
  options: {
    allowedTools: ['Read', 'Edit', 'Glob', 'Grep'],
    permissionMode: 'acceptEdits',
  },
});

for await (const message of result) {
  if (message.type === 'assistant') {
    console.log(message.message.content);
  }
}

query()는 async generator를 돌려준다. 에이전트가 파일을 읽고, 편집하고, 다시 확인하는 과정이 메시지로 스트리밍돼서 그대로 찍어보면 어떤 판단을 하는지 다 보인다.

실제로 걸린 부분

allowedTools를 안 넘기면 기본 도구 세트 전부가 열린다. 나는 처음에 이걸 모르고 돌렸다가 에이전트가 Bash로 npm install까지 시도하는 걸 보고 식겁했다. 필요한 도구만 화이트리스트로 넘기는 게 안전하다. 파괴적인 작업이 걱정되면 permissionMode를 acceptEdits 대신 기본값으로 두고 승인 훅을 붙이면 된다.

또 하나, 이건 Claude API 위에서 도는 거라 ANTHROPIC_API_KEY가 있어야 한다. 없으면 조용히 실패하는 게 아니라 인증 에러가 난다.

한 시간 남짓 만져본 결론은, 파일을 직접 건드리는 자동화(리팩터링, 주석 달기, 테스트 생성)엔 루프를 손으로 짜는 것보다 이쪽이 압도적으로 빠르다는 거다. 반대로 도구가 내 앱 로직 몇 개뿐이라면 굳이 이 큰 걸 끌어올 필요 없이 API 툴 러너로 충분하다. 딱 그 경계만 잡고 쓰면 된다.