ClaudeAgentOptions: 중요한 모든 손잡이

구성 객체

ClaudeAgentOptions가 모든 에이전트 결정이 사는 단일 장소. 작업 디렉토리, 시스템 프롬프트, 허용 도구, MCP 서버, hooks, 모델 선택, max thinking 토큰, env 변수 — 다. Typed config struct로 다뤄, free-for-all kwargs blob X.

가장 자주 만질 필드

cwd(작업 디렉토리), system_prompt(preset, 문자열, 또는 블록 리스트), allowed_tools(tool 이름 리스트; 디폴트 셋에서 restrict), model(어느 Claude tier), permission_mode('default' / 'acceptEdits' / 'bypassPermissions' / 'plan'), mcp_servers(server 이름 → launch config dict), hooks(PreToolUse, PostToolUse 등), env(서브프로세스용 env 변수).

프로덕션에서 bypassPermissions 회피

permission_mode='bypassPermissions'가 모든 permission 게이트 disable. Trusted CI 스크립트엔 유용, user-facing엔 위험. 'default'(인터랙티브 프롬프트) 또는 'acceptEdits'(파일 write만 자동 수락) 디폴트, bypass 필요 시 이유 문서화.

원칙: Options이 정책. 에이전트 행동은 options 객체 모양, 프롬프트 wording X.

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 객체 audit. 모델 핀, allowed_tools가 동작하는 가장 작은 셋, permission_mode 보수적, system_prompt 구조화(stream-of-consciousness X) verify.

Hint

도구가 왜 허용됐는지 기억 못 하면 제거. Breakage가 필요 노출하면 코멘트와 함께 다시 추가.

ClaudeAgentOptions: 중요한 모든 손잡이

구성 객체

가장 자주 만질 필드

프로덕션에서 bypassPermissions 회피

Code

External links

Exercise

Progress

댓글 0