ClaudeAgentOptions가 에이전트 정책을 한곳에 모아

설정 객체가 실행 계약이야

ClaudeAgentOptions에는 작업 디렉터리, 시스템 프롬프트, 허용 도구, MCP 서버, 훅, 모델, 최대 사고 토큰, 환경변수가 들어가. 자유로운 키워드 인자 주머니로 흩뜨리지 말고 타입이 있는 정책 구조체로 다뤄야 어떤 에이전트가 무엇을 할 수 있는지 한눈에 보여.

자주 쓰는 손잡이를 구분해

cwd는 작업 범위, system_prompt는 프리셋이나 직접 쓴 지침, allowed_tools는 허용 도구 목록, model은 Claude 티어를 정해. permission_mode는 default·acceptEdits·bypassPermissions·plan 중 고르고, mcp_servers와 hooks, env가 외부 능력과 실행 환경을 잇지.

bypassPermissions는 운영 기본값이 아니야

permission_mode='bypassPermissions'는 모든 권한 문을 없애. 이미 다른 검토를 통과한 신뢰 가능한 CI에는 쓸 수 있지만 사용자 요청을 받는 에이전트에는 위험해. 기본적으로 default나 파일 편집만 자동 승인하는 acceptEdits를 택하고, 우회가 꼭 필요하면 이유와 피해 범위를 기록해.

원칙: 에이전트 행동은 프롬프트 문구만이 아니라 Options 객체가 정한 정책의 결과야.

Code

프로덕션-shape options 객체·python

from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(
    cwd="/srv/myapp",
    model="claude-sonnet-4-6",
    system_prompt="You are a deployment review assistant. Read CHANGELOG.md and report risks.",
    allowed_tools=["Read", "Grep", "Bash"],  # Write X, Edit X
    permission_mode="default",  # 모든 tool use 전 묻기
    env={"PATH": "/usr/local/bin:/usr/bin"},
    max_thinking_tokens=8192,
)

Read-only로 도구 제한·python

# Agent SDK가 디폴트 도구 리스트 ship; 주어진 에이전트에 subset 화이트리스트.
READ_ONLY_TOOLS = ["Read", "Grep", "Glob", "WebFetch"]

options = ClaudeAgentOptions(
    cwd="/data/audit",
    allowed_tools=READ_ONLY_TOOLS,
    permission_mode="acceptEdits",  # edit 도구 허용 X라 무관
    system_prompt="You are a read-only auditor. Never modify files.",
)

Exercise

Agent SDK 호출 하나의 Options를 감사해. 모델 고정, 필요한 최소 도구, 보수적인 권한 모드, 구조화된 시스템 프롬프트를 확인해.

Hint

도구가 왜 허용됐는지 기억나지 않으면 먼저 빼고, 실제로 필요하면 이유를 주석으로 남겨 다시 넣어.

설정 객체가 실행 계약이야

자주 쓰는 손잡이를 구분해

bypassPermissions는 운영 기본값이 아니야

Code

External links

Exercise

Progress

댓글 0