공식 Claude Agent SDK: 정직하고 감사 가능한 개인 AI 어시스턴트 (2026)
Anthropic의 Claude Agent SDK는 Claude Code와 동일한 도구 루프를 자체 Python 또는 TypeScript 앱에 임베드할 수 있게 합니다. 초보자 규칙: 읽기 전용으로 시작하고, 정직함을 강조하는 system_prompt를 추가한 뒤, 감사 로그가 올바를 때만 allowed_tools를 넓히세요.
함께 보기: SSH로 Claude Code, Cursor Rules vs Skills, Opus 4.8 에이전트 벤치마크.
공식 SDK로 시작하는 이유
래퍼는 어떤 도구가 실행되고 무엇이 머신을 떠나는지 숨기는 경우가 많습니다. SDK는 code.claude.com에서 Read, Edit, Bash, permissions, hooks, sessions를 문서화합니다.
24/7 스케줄용 클라우드 Mac은 선택입니다. 첫 번째 가드된 헬퍼는 노트북만으로도 충분합니다.
SDK 구조
| 계층 | 역할 | 설정 항목 |
|---|---|---|
query() | 에이전트 루프(계획 → 도구 → 관찰) | agent.py |
| Tools | 파일, 셸, 검색, 웹 | allowed_tools |
| Permissions | 승인 / 거부 / 프롬프트 | permission_mode |
| Policy | 정직함, 범위 | system_prompt, CLAUDE.md |
| Audit | 도구 사용 기록 | hooks |
2026년 6월 15일부터 구독 플랜은 별도 크레딧 풀로 Agent SDK를 계량합니다. 무인 루프에 예산을 잡으세요.
8단계 가드 런북
1단계 — 사전 요건
python3 --version # 3.10+
pip install claude-agent-sdk2–3단계 — 프로젝트 + 설치
mkdir my-guarded-agent && cd my-guarded-agent
python3 -m venv .venv && source .venv/bin/activate
pip install claude-agent-sdk4단계 — API 키
# .env (gitignore this file)
ANTHROPIC_API_KEY=sk-ant-...5–6단계 — 정직 프롬프트 + 읽기 전용 실행
from claude_agent_sdk import query, ClaudeAgentOptions
HONEST = """Say "I don't know" when data is missing.
Never invent paths or command output."""
options = ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep"],
permission_mode="dontAsk",
system_prompt=HONEST,
)실행: python3 agent.py — quickstart 참고.
7–8단계 — 감사 hook, 이후 편집
Edit과 permission_mode="acceptEdits"를 켜기 전에 PostToolUse hooks로 audit.log에 기록하세요. 선택: AskUserQuestion으로 확인.
문제 해결
API 키를 찾을 수 없음
해결: 같은 셸에서 ANTHROPIC_API_KEY를 export하세요. .env는 커밋하지 마세요.
pip: No matching distribution
해결: Python 3.10+ 사용; .venv를 다시 만드세요.
thinking.type.enabled not supported
해결: Opus 4.7+에는 Agent SDK를 v0.2.111+로 업그레이드 ([quickstart](https://code.claude.com/docs/en/agent-sdk/quickstart)).
예상치 못한 파일 편집
해결: git으로 되돌리기; hooks가 안전함을 증명할 때까지 dontAsk와 읽기 전용 도구로 복귀.
FAQ
query()와 ClaudeAgentOptions로 임베드하는 라이브러리입니다.dontAsk와 Read, Glob, Grep만.