Agent SDK 구조와 핵심 개념

Claude Agent SDK를 한마디로 정의하면, Claude Code가 내부적으로 돌리는 에이전트 루프를 그대로 라이브러리로 노출한 것이다. 시험에서 가장 먼저 구분해야 하는 것은 Anthropic API를 직접 호출하는 방식과 Agent SDK를 쓰는 방식의 차이다. API를 직접 호출하면 메시지 한 번을 주고받는 단발성 추론을 얻지만, 도구 실행, 도구 결과를 다시 모델에 돌려주는 루프, 권한 확인, 파일 읽기와 쓰기 같은 작업은 모두 개발자가 직접 구현해야 한다. SDK는 이 루프와 내장 도구, 권한 시스템, 서브에이전트, 세션 지속을 모두 제공한다. 따라서 출제 의도는 분명하다. 단순 텍스트 생성이면 API로 충분하고, 도구를 쓰는 자율 작업이면 SDK가 정답이라는 판단을 묻는다.

SDK의 실행 진입점은 두 가지다. 첫째는 query 함수로, 비동기 제너레이터를 반환하는 단발성 실행이다. 프롬프트를 한 번 주면 에이전트가 작업을 마칠 때까지 메시지를 스트리밍하고 종료한다. 매 호출이 새로운 세션을 만들기 때문에 상태가 없는 일회성 작업, 배치 처리, 자동화 스크립트에 적합하다.

# examples/quickstart.pyfrom claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlockoptions = ClaudeAgentOptions(    system_prompt="You are a Python expert",    allowed_tools=["Read", "Edit", "Bash"],    model="claude-opus-4-8",)async for message in query(prompt="Create a Python web server", options=options):    if isinstance(message, AssistantMessage):        for block in message.content:            if isinstance(block, TextBlock):                print(block.text)

둘째는 ClaudeSDKClient로, 컨텍스트 매니저로 열어 두고 여러 차례 양방향으로 대화하는 대화형 실행이다. 한 번 연결한 세션 안에서 query로 메시지를 보내고 receive_response로 응답을 받기를 반복할 수 있어, 후속 질문이 이전 맥락을 이어 가야 하는 대화형 애플리케이션, 챗봇, 사람이 중간에 개입하는 워크플로우에 쓴다. 시험의 단골 함정은 이 둘을 뒤집어 제시하는 것이다. 멀티턴 대화에 query를 반복 호출하도록 유도하거나, 단발 배치에 굳이 ClaudeSDKClient를 띄우게 한다. 멀티턴이면 ClaudeSDKClient, 일회성이면 query가 기본값임을 기억하면 된다.

동작은 ClaudeAgentOptions로 제어한다. system_prompt로 역할을 지정하고, model로 사용할 모델을 고르며, mcp_servers로 외부 도구를, cwd로 작업 디렉터리를 정한다. 권한은 두 축으로 나뉜다. allowed_tools는 권한 프롬프트 없이 자동 실행할 도구를 미리 승인하는 목록이고, permission_mode는 그 목록에 없는 도구를 만났을 때의 기본 동작을 정한다. 여기서 가장 자주 틀리는 포인트가 있다. allowed_tools는 도구를 "사전 승인"할 뿐 도구의 "사용 가능 여부"를 결정하지 않는다. 도구 자체는 내장 도구나 mcp_servers를 통해 공급되며, allowed_tools에 없다고 도구가 사라지는 것이 아니라 실행 시 권한 확인을 거치게 될 뿐이다. 반대로 특정 도구를 아예 막으려면 disallowed_tools를 쓴다.

permission_mode의 값은 정확히 외워야 한다. default는 위험한 작업에 대해 표준적으로 확인을 요청하고, acceptEdits는 파일 편집 계열을 자동 승인하며, plan은 도구를 실행하지 않고 분석만 하는 계획 모드다. bypassPermissions는 모든 도구를 확인 없이 실행하므로 운영 환경에서 위험하고, dontAsk는 사전 승인되지 않은 도구를 묻지 않고 그대로 거부한다. 시험은 bypassPermissions의 위험성과 plan 모드가 실제로 아무 도구도 실행하지 않는다는 점을 자주 묻는다.

정리

• query는 단발성 비동기 제너레이터로 상태 없는 일회성 작업에, ClaudeSDKClient는 양방향 컨텍스트 매니저로 멀티턴 대화에 쓴다.
• Agent SDK는 도구 루프, 권한, 서브에이전트, 세션 지속을 내장한다. 단순 텍스트 생성이면 API 직접 호출, 도구 기반 자율 작업이면 SDK가 정답이다.
• allowed_tools는 권한 프롬프트를 건너뛸 도구를 사전 승인할 뿐 도구의 존재 여부를 결정하지 않는다. 차단은 disallowed_tools가 담당한다.
• permission_mode는 default, acceptEdits, plan, bypassPermissions, dontAsk로 구분된다. plan은 도구를 실행하지 않고 bypassPermissions는 모든 확인을 건너뛴다.
• 모델 지정은 claude-opus-4-8을 기본으로 하며, 동작 제어는 모두 ClaudeAgentOptions를 통해 이루어진다.