Claude Agent SDK로 내 업무용 AI 비서 만들기 — 초보자 10단계 실전 가이드

Claude Agent SDK 이거 처음 만지고 나서 제가 만들던 업무 자동화 코드가 확 짧아졌어요. 파이썬 잘 모르는 분도 3일이면 '내 업무 비서' 한 명 만들 수 있어요. 2026년 4월 23일 기준으로 제가 밟은 경로를 10단계로 풀어볼게요.

1단계: Anthropic 콘솔 계정 생성 + API 키 발급

console.anthropic.com에 가입하면 소액의 무료 크레딧이 붙어요. 금액과 사용 조건은 계정·시점에 따라 달라지니 콘솔에서 직접 확인하세요. 이걸로 가벼운 테스트 호출을 여러 번 해볼 수 있어요. API 키는 'sk-ant-'로 시작하는 문자열인데, 절대 깃헙이나 슬랙에 복사하지 마세요. 공개된 곳에 키가 노출되면 곧바로 무효 처리될 수 있으니, 커밋 전에 한 번 더 확인하는 습관을 들이세요.

2단계: 파이썬 3.10+ 설치, 가상환경 만들기

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install anthropic

여기까지 5분. 프로젝트별로 가상환경 분리하는 습관을 들이면 버전 꼬임 사고가 절반으로 줄어요.

3단계: 첫 호출 — "Hello Claude"

from anthropic import Anthropic
client = Anthropic()
msg = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=100,
    messages=[{"role": "user", "content": "오늘 날씨 어때?"}],
)
print(msg.content[0].text)

환경변수 ANTHROPIC_API_KEY를 설정해두면 Anthropic() 생성자에 키를 안 넘겨도 돼요.

4단계: 프롬프트 캐싱 켜기 (비용 90% 절감)

긴 시스템 프롬프트가 매번 반복될 때 켜면 좋아요. cache_control 파라미터를 붙이면 그 부분이 기본 5분(옵션으로 1시간) 동안 캐시돼요. 두 번째 호출부터는 캐시된 입력이 원래 값의 10분의 1 수준으로 읽혀요. 반복 호출이 잦을수록 월 비용이 체감으로 확 줄어요.

5단계: Tool Use — 계산기부터 시작

에이전트의 핵심은 '툴'이에요. 제일 간단한 계산기 툴 하나 붙여보세요.

tools = [{
    "name": "calculator",
    "description": "두 숫자의 사칙연산을 수행",
    "input_schema": {"type": "object", "properties": {
        "op": {"type": "string"}, "a": {"type": "number"}, "b": {"type": "number"}
    }}
}]

Claude가 툴을 '써야겠다'고 판단하면 stop_reason이 "tool_use"로 나오고, 그 결과를 다시 넣어주는 루프를 짜는 게 다예요.

툴 루프, 실제로 어떻게 도는지

5단계에서 '루프'라고만 하고 넘어갔죠. 이게 에이전트의 심장이라 조금 더 풀게요. 흐름은 마치 탁구 랠리 같아요.

• 내가 질문을 보내요.
• Claude가 '툴 써야겠다' 판단하면 stop_reason이 tool_use로 와요.
• 제가 그 툴을 실제로 실행해요. 파이썬 함수 하나 부르는 거죠.
• 결과를 tool_result에 담아 다시 보내요. 이때 tool_use_id를 꼭 맞춰요.
• Claude가 그 결과로 최종 답을 주거나, 다른 툴을 또 불러요.

stop_reason이 end_turn이 될 때까지 이 왕복을 반복하면 돼요. 반복 상한을 안 걸면 툴을 계속 부르다 토큰이 새기도 해요. 그래서 저는 최대 5번쯤에서 끊어둬요. 이 루프만 손에 익으면 나머지는 툴 종류만 바꿔 끼우는 복사·붙여넣기예요.

잠깐 — 'Claude Agent SDK'와 기본 SDK, 뭐가 다를까

여기서 많이 헷갈리는 지점 하나 짚고 갈게요. 위 3~5단계 예제는 사실 anthropic 기본 SDK예요. 메시지를 주고받고, 툴 루프를 제가 직접 짜는 방식이죠.

'Claude Agent SDK'는 이름만 비슷한 딴 패키지예요. claude-agent-sdk로 따로 설치해요. 쉽게 말해 Claude Code를 라이브러리로 감싼 거예요. 파일 읽기·쓰기·편집, bash 실행, 웹 검색 같은 툴이 처음부터 들어 있어요.

차이를 요리에 빗대볼게요. 기본 SDK는 칼이랑 도마만 줘요. '알아서 썰어' 하는 거죠. Agent SDK는 손질까지 된 밀키트예요. 파일을 만지는 에이전트라면 이쪽이 훨씬 빨라요.

그럼 초보는 뭘로 시작할까요. 저는 이렇게 갈라요. 한 번 묻고 한 번 답하는 챗봇이나 요약기면 기본 SDK로 충분해요. '내 폴더 뒤져서 정리해줘' 같은 일이면 Agent SDK로 넘어가세요. 툴 루프를 직접 안 짜도 되거든요.

6단계: 실전 예제 ① — 이메일 초안 작성기

제가 매일 받는 광고 제안 메일에 정중히 거절 답장 쓰는 게 지겨워서 만든 에이전트예요. 받은 메일 텍스트를 붙여넣으면 금방 제 톤으로 답장 초안이 나와요. 첫 2주 동안 반복 답장을 꽤 많이 처리했는데, 체감상 몇 시간은 아낀 것 같아요.

7단계: 실전 예제 ② — 회의록 요약기

Zoom 녹음 전사본을 던지면 '핵심 결정 / 담당자별 액션 아이템 / 다음 회의 안건'으로 구조화해줘요. 20분짜리 회의도 몇 초면 요약이 나와요. 회사 전체에 돌릴 땐 Slack 봇으로 확장할 수 있어요.

8단계: 실전 예제 ③ — 보고서 목차 생성기

예를 들어 '2026년 2분기 마케팅 보고서' 같은 주제를 던지면 경쟁사 리포트 구조를 참고해 목차 초안을 뽑아줘요. Claude 4.7의 긴 컨텍스트(1M 토큰) 덕에 PDF 여러 개를 한꺼번에 참조할 수도 있어요.

더 깊이 들어가고 싶다면 Claude AI 사용법 초보 가이드에 콘솔 UI부터 정리돼 있고, 모델 선택 기준은 Claude 4.7 vs Gemini 2.5 Pro vs ChatGPT-5 실사용 비교 쪽이 편하실 거예요.

9단계: 24시간 돌아가는 서버에 배포하기

파이썬 에이전트를 로컬에서만 돌리면 컴퓨터를 켜놔야 해서 귀찮아요. 여기서 한 가지 짚을 게 있어요. 파이썬 코드와 그 의존성을 그대로 실행하려면 파이썬이 도는 환경이 필요해요. 그래서 작은 클라우드 서버(VPS)나 컨테이너에 올리는 게 무난해요. 저가형이면 월 몇 달러 선이고 24시간 돌아가요. 저는 텔레그램 봇 형태로 연결해서 폰에서 바로 쓰고 있어요.

10단계: 로그 관리 + 비용 알림

마지막 단계가 가장 중요해요. 실수로 루프가 새면 토큰이 순식간에 불어날 수 있거든요. 저는 Anthropic 콘솔의 Usage 알림에 일일 한도를 걸어뒀고, 사용량을 매일 슬랙으로 받아봐요. 이 조합을 쓴 뒤로는 요금 사고가 한 번도 없었어요.

초보가 자주 밟는 지뢰 3가지

제가 3일 만들면서 밟았거나, 옆에서 본 실수들이에요.

첫째, API 키를 코드에 박아두기. 키를 소스에 그냥 적으면 깃헙에 올리는 순간 털려요. 3단계에서 본 것처럼 환경변수 ANTHROPIC_API_KEY로 빼두면 돼요.

둘째, max_tokens를 너무 짜게 주기. 답이 중간에 뚝 끊기면 십중팔구 이거예요. 짧은 분류면 작아도 돼요. 보고서나 긴 글이면 넉넉히 주세요. 출력이 길어질 것 같으면 스트리밍으로 받는 게 안전해요.

셋째, 캐싱이 걸린 줄 착각하기. cache_control만 붙이면 끝이 아니에요. 시스템 프롬프트 맨 앞에 오늘 날짜나 세션 아이디가 있으면 캐시가 통째로 깨져요. 매번 값이 바뀌니까요. 응답 usage에서 cache_read_input_tokens가 계속 0이면 앞부분이 바뀌는 중이란 신호예요.

비용, 겁먹지 않아도 되는 이유

개인 업무용이면 생각보다 안 나와요. 앞서 본 캐싱(4단계)과 사용량 알림(10단계)이 큰 몫을 해요. 여기에 하나만 더 챙기면 되는데, 바로 모델 선택이에요.

무조건 제일 센 모델을 쓸 필요는 없어요. 단순 분류나 요약이면 가벼운 모델로 내려도 품질 차이가 잘 안 느껴져요. 어려운 추론만 상위 모델에 맡기면 돼요. 이 세 가지를 함께 쓰면 매달 커피 두어 잔 값 안에서 굴릴 수 있어요.

배포는 세 갈래로 갈려요

9단계에서 작은 클라우드 서버(VPS)를 골랐는데, 사실 길이 셋이에요. 상황 보고 고르면 돼요.

첫째, 로컬에서만 굴리기. 내 PC가 켜져 있을 때만 돌아가요. 테스트나 개인 용도면 여기서 시작해요.

둘째, 서버(VPS)나 컨테이너에 올리기. 파이썬이 그대로 도니까 24시간 돌고 폰에서도 불러 써요. 저는 텔레그램 봇에 연결해뒀어요.

셋째, 관리형 실행 환경에 얹기. 에이전트 루프와 툴 실행 환경까지 대신 돌려주는 관리형 서비스를 쓰는 방식이에요. 서버 관리가 부담이면 이 길이 편해요. 대신 세팅이 기본 SDK보다 무겁고, 어떤 선택지가 제공되는지는 시점마다 달라지니 공식 문서에서 직접 확인하세요.

정답은 없어요. 처음엔 로컬, 손에 익으면 서버, 규모가 커지면 관리형 환경. 이 순서가 무난하더라고요.

배포 전 5분 체크리스트

에이전트를 완성했으면, 내보내기 전에 이것만 훑어보세요.

• API 키를 환경변수로 뺐나요? 코드에 남아 있으면 지금 지우세요.
• max_tokens가 넉넉한가요? 긴 출력이면 스트리밍으로 받나요?
• 캐싱이 진짜 걸리는지 usage로 확인했나요? cache_read 값이 찍혀야 제대로 된 거예요.
• 툴 루프에 반복 상한을 걸었나요? 무한 루프면 토큰이 순식간에 새요.
• 비용 알림을 켰나요? 콘솔 Usage 일 한도 알림 하나면 사고를 막아요.

다섯 개 다 초록불이면 이제 켜도 돼요. 저는 이 체크리스트를 쓰고 나서 새벽에 토큰 폭주로 깨는 일이 없어졌어요.

여기에 하나 더 얹자면, 첫 배포는 작게 가세요. 툴 하나, 기능 하나만 켜고 하루 돌려보는 거예요. 이상 없으면 그때 툴을 붙여 나가면 돼요. 처음부터 열 개 기능을 다 넣으면 어디서 새는지 못 찾거든요. 저도 이메일 초안기 하나만 2주 굴린 다음에 회의록 요약기를 붙였어요.

3일 공부 + 주말 구축으로 얻은 체감 변화

• 주간 이메일 작업 시간: 체감상 3분의 1 수준으로 줄었어요
• 회의록 정리 시간: 20분 넘게 걸리던 게 몇 분으로 짧아졌어요
• 월 API 비용: 대략 커피 몇 잔 값 안쪽 (계정·사용량에 따라 달라요)

대기업 자동화 솔루션은 견적이 꽤 비싸요. 개인이 Claude Agent SDK로 직접 만들면 그 일부 비용으로 비슷한 효과를 낼 수 있어요. 첫 툴 하나만 돌아가면 나머진 복사 붙여넣기로 확장할 수 있으니, 이번 주말에 1번부터 5번까지만 해보세요.