핵심 요약
Anthropic이 공개한 Claude Agent SDK는 Claude Code CLI와 동일한 자율 에이전트 루프를 Python·TypeScript 애플리케이션에 임베드할 수 있게 해 준다(Anthropic 공식 문서, 2026). query() 함수 하나로 프롬프트를 넘기면 모델이 파일 읽기·편집·셸 실행·웹 검색 등 내장 도구를 연속 호출하고, 결과를 다시 컨텍스트에 넣어 도구 호출이 없을 때까지 반복한다. 2026년 6월 15일부터 Agent SDK·GitHub Actions 사용량은 대화형 Claude Code와 별도 과금 풀로 분리됐다(〈Totalum Blog〉 2026-06-15). 개발팀 입장에서 핵심은 "모델 API를 직접 래핑해 도구 루프를 구현"하는 대신, 검증된 하네스 위에 비즈니스 로직만 얹는 선택지가 생겼다는 점이다.
무슨 일이 있었나
Agent SDK의 루프는 다섯 단계로 돌아간다(Anthropic 공식 문서 «How the agent loop works», 2026):
1. 프롬프트 수신 — 시스템 프롬프트·도구 목록·권한 설정 로드
2. 모델 추론 — Claude가 다음 행동(텍스트 응답 또는 도구 호출) 결정
3. 도구 실행 — SDK가 Read, Edit, Bash, Glob, WebSearch 등 요청을 실행
4. 반복 — 도구 결과를 다시 모델에 전달, turn 단위로 순환
5. 종료 — 도구 호출 없는 최종 응답과 ResultMessage(토큰·비용·세션 ID) 반환
Python 예시는 다음과 같다:
`python
from claude_agent_sdk import query, ClaudeAgentOptions
async for message in query(
prompt="auth.py의 크래시 버그를 찾아 수정해",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob"],
permission_mode="acceptEdits",
max_turns=20,
max_budget_usd=5.0,
),
):
...
`
Turn은 "모델 출력 → 도구 실행 → 결과 피드백" 한 사이클이다. 여러 turn이 한 번의 async for 반복 안에서 처리되며, 호출 코드는 중간에 개입하지 않는다(〈harnez.ai〉 2026). 개발자가 제어하는 지점은 hooks(도구 실행 전 가로채기·차단·로깅), max_turns, max_budget_usd, permission_mode다.
Client SDK(직접 Messages API 호출)와의 차이도 중요하다. Client SDK는 도구 루프를 직접 구현해야 하지만, Agent SDK는 Claude Code와 같은 내장 루프·컨텍스트 관리·재시도를 제공한다(Anthropic «Agent SDK overview», 2026). Managed Agents REST API는 Anthropic 인프라에서 샌드박스를 돌리는 반면, Agent SDK는 자사 프로세스·파일시스템 위에서 동작한다.
실무 관점: 어디에 쓰고 어디서 멈출까
적합한 용도: CI 파이프라인의 자동 코드 리뷰·수정, 내부 도구의 "자연어 → 파일 변경" 워크플로, MCP 서버와 연동한 사내 에이전트. Boris Cherny(Claude Code 리드)는 Meta @Scale(2026-06-19)에서 "에이전트가 에이전트를 프롬프트하는" 재귀 루프가 2026년 하반기 코딩 패러다임이 될 것이라고 말했다(〈AIntelligenceHub〉 2026-06-22).
주의점: (1) 비용 상한 — max_budget_usd 없이 장시간 루프를 돌리면 예상 밖 과금 가능. (2) 권한 범위 — permission_mode="acceptEdits"는 파일 변경을 자동 승인하므로, 프로덕션 브랜치에 직접 연결하면 위험. (3) 프로그래매틱 API — TypeScript 7.0 RC와 마찬가지로, Agent SDK도 "라이브러리 ≠ 모델"이라 도구 실행 결과 검증은 여전히 애플리케이션 책임이다.
고유 인사이트: 많은 팀이 "에이전트 = LLM API + function calling"으로 시작하지만, Agent SDK 문서가 강조하는 건 turn 단위 오케스트레이션과 hooks다. 즉 경쟁력은 모델 선택보다 루프 상태를 관찰·중단·감사(audit)할 수 있는 운영 레이어를 먼저 설계하는 쪽에 있다. Claude Code CLI를 쓰던 팀은 동일한 옵션 이름(allowed_tools, max_turns)으로 터미널 → 서비스 전환 비용을 줄일 수 있다.
체크포인트와 리스크
- 체크포인트
- Pro/Max 플랜의 Agent SDK 별도 크레딧 풀 잔량·초과 과금 정책
- hooks로 위험 명령(
rm -rf, prod DB) 하드 블록 여부 - 세션 JSONL 저장 위치·PII 마스킹
- subagent·MCP 서버 추가 시 turn·비용 증폭
- 리스크 요인
- 무제한 루프로 동일 버그 수정 반복(비용·시간)
- 자동 편집이 테스트 없이 머지되는 파이프라인 설계
- Client SDK와 혼용 시 "어느 tsc/agent가 실행 중인지" 혼선
마무리
Claude Agent SDK는 2026년 현재 "Claude Code를 코드로 부르는" 가장 직접적인 경로다. query() + ClaudeAgentOptions 조합으로 turn·비용·권한을 명시하고, hooks로 가드레일을 두면 터미널 없이도 자율 코딩 에이전트를 서비스에 붙일 수 있다. 다만 Cherny가 말한 재귀 루프 시대가 오려면, 플랫폼마다 "루프 상태·지속 시간·비용"을 개발자에게 보여 주는 관리 UI가 표준이 될 것이다 — SDK를 도입할 때 로그·중단·예산부터 먼저 잡는 편이 안전하다.
참고 자료
'개발이야기' 카테고리의 다른 글
| TypeScript 7.0 RC: Go 네이티브 컴파일러가 CI를 10배 빠르게 만드는 조건 (0) | 2026.06.29 |
|---|---|
| Ouro Loop: Claude Code·Cursor에 '경계 있는 자율' 루프를 거는 오픈소스 프레임워크 (0) | 2026.06.29 |
| n8n 2.28.0: GitHub Pull Request 노드가 자동화 파이프라인에 주는 변화 (0) | 2026.06.28 |
| MirrorCode 벤치마크: AI가 1만6천 줄 코드베이스를 14시간에 재구현한 이유 (0) | 2026.06.28 |
| GitHub Desktop 3.6: Git worktree와 Copilot 머지 충돌 해결이 바꾸는 일상 (0) | 2026.06.28 |