Claude Code 상세 사용법 47: Agent SDK 권한과 세션 설계 | DAKER 커뮤니티

Claude Code 상세 사용법 47: Agent SDK 권한과 세션 설계

Claude Agent SDK는 Claude Code의 agentic loop를 Python이나 TypeScript 코드 안에서 쓰게 해주는 방식입니다. 공식 quickstart는 query, prompt, options, streaming message 처리를 핵심으로 설명합니다. 이번 글은 “돌아가는 예제”보다 운영에 필요한 권한과 세션 설계에 초점을 둡니다.

최소 설치

Python은 3.10 이상, Node는 18 이상이 필요합니다. Python 예시는 다음처럼 시작합니다.

uv init
uv add claude-agent-sdk

또는 venv를 직접 만들 수 있습니다.

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

SDK 인증은 API key 기반으로 설계합니다. 문서에는 Bedrock, Vertex AI, Claude Platform on AWS, Microsoft Foundry 같은 provider 환경변수도 안내되어 있습니다. 비밀값은 코드에 쓰지 말고 실행 환경에서 주입하세요.

첫 agent 구조

SDK 예제의 핵심은 async iterator입니다. Claude가 생각하고, 도구를 호출하고, 결과를 읽고, 다시 판단하는 흐름을 메시지로 받습니다.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="utils.py의 crash 가능성을 찾고 고쳐줘.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",
        ),
    ):
        print(type(message).__name__)

asyncio.run(main())

처음부터 모든 메시지를 예쁘게 숨기지 마세요. 개발 중에는 tool call, ResultMessage, 오류 이벤트를 로그로 남겨야 실패 원인을 빨리 찾습니다.

권한은 제품 요구사항이다

allowed_tools는 agent가 사용할 수 있는 표면을 제한합니다. 읽기 전용 분석이면 Read, Glob 정도로 시작하세요. 파일 수정 agent라면 Edit를 열고, shell 실행은 필요한 명령만 좁게 허용하는 편이 안전합니다.

permission_mode는 사용자 승인 흐름을 어떻게 처리할지 결정합니다. 예제의 acceptEdits는 파일 편집 자동화에는 편하지만, 외부 side effect까지 안전하다는 뜻은 아닙니다. 배포, DB migration, 고객 데이터 접근은 hooks, allow rule, 별도 human gate를 붙여야 합니다.

세션을 이어갈지 끊을지 정한다

세션 문서는 continue, resume, fork 같은 패턴을 다룹니다. 긴 코드 리뷰나 리팩터링은 session id를 저장해 재개할 수 있습니다. 하지만 매일 도는 테스트 자동화는 이전 대화가 섞이면 오히려 위험합니다.

반복 CI 검사: 새 세션, 좁은 컨텍스트
긴 리팩터링: session id 저장 후 resume
대안 비교: 기존 세션에서 fork
장애 분석: 로그와 수정 내역을 함께 저장

운영 실패 모드

첫째, 권한이 넓어서 agent가 너무 많은 파일을 만집니다. 작업 디렉터리, prompt, allowed tools를 함께 좁히세요. 둘째, 세션을 무조건 resume해서 낡은 가정이 따라옵니다. 반복 작업은 새 세션이 기본입니다. 셋째, 결과만 저장하고 근거를 버립니다. ResultMessage, 테스트 로그, diff summary를 같이 남겨야 코드 리뷰와 테스트 자동화가 가능합니다.

선임 엔지니어 관점

Agent SDK로 만든 LLM 개발 워크플로우는 작은 백엔드 서비스처럼 다뤄야 합니다. 입력 스키마, 권한 모델, 세션 수명, 관측 로그, 실패 재시도, 비용 추적이 설계 대상입니다. “Claude가 알아서 고친다”보다 “어떤 상태를 기억하고, 무엇을 만지고, 성공을 어떻게 증명하는가”를 먼저 정하면 운영 가능한 agentic coding이 됩니다.

참고: Claude Code 공식 Agent SDK quickstart, sessions, permissions 문서를 기준으로 작성했습니다.

Redirecting to Claude Code 상세 사용법 47: Agent SDK 권한과 세션 설계 | DAKER 커뮤니티...