Claude Agent SDK: 서브에이전트와 세션 저장소(Subagents and Session Store)

Claude Agent SDK는 Claude Code 하네스(harness)를 라이브러리 형태로 제공한 것입니다. 내장 도구(built-in tools), 컨텍스트 격리를 위한 서브에이전트(subagents), 라이프사이클 훅(hooks), W3C 트레이스 전파(trace propagation), 세션 저장소(session store) 호환성을 함께 제공합니다. Claude Managed Agents는 오래 실행되는 비동기 작업을 위한 호스팅형 대안입니다.

유형: Learn + Build 언어: Python (표준 라이브러리) 선수 학습: Phase 14 · 01 (에이전트 루프), Phase 14 · 10 (스킬 라이브러리) 소요 시간: 약 75분

학습 목표

• Anthropic 클라이언트 SDK(Anthropic Client SDK; raw API)와 Claude Agent SDK(하네스 형태)의 차이를 설명합니다.
• 서브에이전트(subagents)의 두 가지 용도, 즉 병렬화(parallelization)와 컨텍스트 격리(context isolation)를 설명하고 언제 사용할지 판단합니다.
• Python SDK의 세션 저장소(session store) 표면(append, load, list_sessions, delete, list_subkeys)과 --session-mirror의 역할을 말할 수 있습니다.
• 내장 도구, 격리된 컨텍스트를 갖는 서브에이전트 생성(spawning), 라이프사이클 훅, 세션 저장소를 갖춘 표준 라이브러리 기반 하네스를 구현합니다.

문제

원시 LLM API(raw LLM API)는 단 한 번의 왕복 호출(round-trip)만 제공합니다. 그러나 프로덕션에서 동작하는 에이전트에는 도구 실행, MCP 서버, 라이프사이클 훅, 서브에이전트 생성, 세션 영속화(session persistence), 트레이스 전파(trace propagation)가 모두 필요합니다. Claude Agent SDK는 바로 이 형태를 라이브러리로 묶어 제공합니다. 즉, Claude Code가 내부적으로 사용하는 것과 동일한 하네스를, 사용자 정의 에이전트에서 그대로 활용할 수 있도록 노출한 것입니다.

개념

클라이언트 SDK와 에이전트 SDK 비교(Client SDK vs Agent SDK)

• 클라이언트 SDK(anthropic). 원시 메시지 API(raw Messages API)입니다. 루프, 도구, 상태를 모두 직접 관리합니다.
• 에이전트 SDK(claude-agent-sdk). 내장 도구 실행, MCP 연결, 훅, 서브에이전트 생성, 세션 저장소를 함께 제공합니다. Claude Code의 루프를 라이브러리 형태로 사용하는 셈입니다.

내장 도구(Built-in tools)

SDK는 파일 읽기/쓰기, 셸(shell), grep, glob, 웹 가져오기(web fetch) 등 10개가 넘는 도구를 기본으로 제공합니다. 사용자 정의 도구는 표준 도구 스키마 인터페이스(tool-schema interface)를 통해 등록합니다.

서브에이전트(Subagents)

Anthropic 문서가 정리하는 용도는 두 가지입니다.

1. 병렬화(Parallelization). 서로 독립적인 작업을 동시에 수행합니다. 예를 들어 "이 20개 모듈 각각의 테스트 파일을 찾아라"는 20개의 병렬 서브에이전트 작업이 됩니다.
2. 컨텍스트 격리(Context isolation). 각 서브에이전트는 자신만의 컨텍스트 창(context window)을 사용하고, 결과만 오케스트레이터(orchestrator)로 돌려보냅니다. 그 결과 오케스트레이터의 컨텍스트 예산(context budget)이 그대로 보존됩니다.

Python SDK에는 최근 서브에이전트의 대화 기록(transcript)을 읽기 위한 list_subagents(), get_subagent_messages()가 추가되었습니다.

세션 저장소(Session store)

TypeScript 구현과 프로토콜 호환성(parity)을 가집니다.

• append(session_id, message) — 대화 턴을 추가합니다.
• load(session_id) — 대화를 복원합니다.
• list_sessions() — 세션 목록을 나열합니다.
• delete(session_id) — 서브에이전트 세션까지 연쇄(cascade) 삭제합니다.
• list_subkeys(session_id) — 서브에이전트 키를 나열합니다.

--session-mirror(CLI 플래그)는 디버깅을 위해 대화 기록이 스트리밍되는 동안 외부 파일에 그대로 미러링합니다.

훅(Hooks)

등록할 수 있는 라이프사이클 훅은 다음과 같습니다.

• PreToolUse, PostToolUse — 도구 호출을 차단하거나 감사(audit)합니다.
• SessionStart, SessionEnd — 세션의 초기화와 정리를 수행합니다.
• UserPromptSubmit — 모델이 입력을 보기 전에 사용자 프롬프트에 개입합니다.
• PreCompact — 컨텍스트 압축(compaction) 직전에 실행됩니다.
• Stop — 에이전트 종료 시 정리 작업을 수행합니다.
• Notification — 사이드 채널 알림(side-channel alert)을 보냅니다.

훅은 pro-workflow(Phase 14 커리큘럼 참조) 같은 시스템이 횡단 관심사(cross-cutting behavior)를 추가하는 표준적인 방식입니다.

W3C 트레이스 컨텍스트(W3C trace context)

호출자(caller) 측에서 활성화된 OTel 스팬(span)은 W3C 트레이스 컨텍스트 헤더를 통해 CLI 서브프로세스로 전파됩니다. 그 결과 다중 프로세스에 걸친 전체 추적이 백엔드에서 하나의 트레이스로 묶여 보입니다.

Claude Managed Agents

호스팅형 대안으로, 베타 헤더는 managed-agents-2026-04-01입니다. 오래 실행되는 비동기 작업, 내장 프롬프트 캐싱(prompt caching), 내장 컨텍스트 압축(compaction)을 제공합니다. 제어권의 일부를 내려놓는 대신 관리형 인프라(managed infrastructure)를 얻는 선택지입니다.

이 패턴이 잘못되는 지점

• 서브에이전트 과다 생성(Subagent over-spawn). 작은 작업 100개에 서브에이전트 100개를 띄우면 오버헤드가 작업 비용을 압도합니다. 대신 묶어서(batching) 처리하세요.
• 훅 과잉(Hook creep). 모든 팀이 훅을 계속 추가하면 시작 시간(startup time)이 부풀어 오릅니다. 분기마다 훅 등록 현황을 점검하세요.
• 세션 비대화(Session bloat). 세션이 누적되면서 크기가 계속 늘어납니다. list_sessions와 만료 정책(expiry policy)을 함께 사용하세요.

만들어보기

code/main.py는 SDK의 형태를 Python 표준 라이브러리만으로 구현합니다.

• Tool, ToolRegistry와 내장 도구 read_file, write_file, list_dir.
• Subagent — 비공개 컨텍스트, 격리된 실행, 결과 반환.
• SessionStore — append, load, list, delete, list_subkeys.
• Hooks — pre_tool_use, post_tool_use, session_start, session_end.
• 데모 — 메인 에이전트가 서브에이전트 3개를 병렬로 생성하고(각각 격리), 결과를 모은 뒤 세션을 저장합니다.

실행 방법은 다음과 같습니다.

python3 code/main.py

실행 결과를 추적해 보면 서브에이전트의 컨텍스트 격리가 그대로 드러납니다. 즉, 오케스트레이터의 컨텍스트 크기는 제한된 상태로 유지되고, 훅 실행과 세션 영속화가 함께 일어나는 모습을 확인할 수 있습니다.

사용해보기

• Claude Agent SDK는 Claude 중심 제품(Claude-first product)에서 Claude Code 하네스 형태를 그대로 활용하고 싶을 때 사용합니다.
• Claude Managed Agents는 호스팅 환경에서 장기 실행 비동기 작업을 다룰 때 적합합니다.
• OpenAI Agents SDK(16강)는 OpenAI 중심(OpenAI-first) 대응 라이브러리입니다.
• LangGraph와 사용자 정의 도구(LangGraph + custom tools)는 그래프 형태의 상태 머신을 원할 때 선택합니다.

산출물 만들기

outputs/skill-claude-agent-scaffold.md는 서브에이전트, 훅, 세션 저장소, MCP 서버 연결(MCP server attachment), W3C 트레이스 전파를 갖춘 Claude Agent SDK 앱을 스캐폴딩(scaffold)합니다.

연습문제

1. (쉬움) 20개 작업을 병렬 서브에이전트 5개씩 묶어 처리하는 서브에이전트 스포너(spawner)를 추가하세요. 작업당 서브에이전트 하나를 띄우는 방식과 오케스트레이터 컨텍스트 크기를 비교합니다.
2. (중간) write_file 호출을 세션당 분당 5회로 제한하는 PreToolUse 훅을 구현하세요. 동작을 추적(trace)해 봅니다.
3. (중간) list_subkeys를 사용해 서브에이전트 트리를 렌더링하세요. 깊은 중첩은 어떤 형태로 보이나요?
4. (어려움) 이 장난감 구현을 실제 claude-agent-sdk Python 패키지로 옮겨보세요. 도구 등록(tool registration)에서 무엇이 달라지나요?
5. (어려움) Claude Managed Agents 문서를 읽어보세요. 자체 호스팅(self-hosted)에서 관리형(managed)으로 갈아탈 만한 시점은 언제인가요?

핵심 용어

더 읽을거리

• Claude Agent SDK overview — Claude Code의 라이브러리 형태에 대한 개요입니다.
• Anthropic, Building agents with the Claude Agent SDK — 프로덕션 패턴을 정리한 글입니다.
• Claude Managed Agents overview — 호스팅형 대안에 대한 안내입니다.
• OpenAI Agents SDK — OpenAI 측 대응 라이브러리입니다.