Claude Agent SDK, 도대체 뭘 만들 수 있는 물건이야

지난주에 개발자 커뮤니티 슬랙에서 누군가 "Agent SDK 써봤어요?" 하고 물어보는 걸 봤어요. 댓글이 순식간에 달렸는데, 절반은 "좋아요", 절반은 "그게 뭐예요?" 였거든요. 저도 처음엔 후자였습니다. Claude API는 몇 달째 쓰고 있었는데, Agent SDK는 뭔가 다른 물건처럼 들렸고, 선뜻 찾아볼 엄두가 안 났어요.

그래서 이 글은 그때의 저한테 쓰는 글이기도 해요. "API는 쓸 줄 아는데 Agent SDK는 처음 들어봤다"는 그 지점에서 시작합니다.

API랑 Agent SDK, 뭐가 다른 거야

솔직히 말하면, 처음엔 그냥 API의 업그레이드 버전인 줄 알았어요. 근데 아니에요. 결이 다릅니다.

Claude API는 — 처음 연결하는 날을 기억하는 분들은 잘 아시겠지만 — 기본적으로 "질문 하나 던지면 대답 하나 돌아온다"는 구조예요. 요청 하나, 응답 하나. 심플하죠. 챗봇 만들고, 텍스트 요약하고, 번역하는 데는 이걸로 충분해요.

그런데 Agent SDK는 달라요. "여러 단계로 이어지는 작업을 AI가 스스로 판단하면서 처리하게 해주는 틀"이라고 보면 돼요. 쉽게 말하면 이런 거예요. 여행 일정 짜달라고 했을 때, API는 "서울에서 도쿄 3박4일이면 이런 코스 어때요?" 한 번 답하고 끝나요. 반면 Agent SDK 기반으로 만든 앱이라면, 일정 후보를 뽑고 → 날씨 API 찌르고 → 숙소 예약 사이트에서 가격 확인하고 → 최종안을 정리해서 보여주는 흐름을 연결할 수 있어요.

한 번의 요청이 아니라, 여러 도구를 넘나드는 연속 작업. 그게 핵심입니다.

비유로 이해해보면

제가 가장 와닿았던 비유는 "직원 vs 도구"예요.

Claude API는 엄청나게 박식한 도구예요. 쓸 때마다 꺼내 들고, 질문하고, 다시 넣어두는. 도구는 제가 어떻게 활용하느냐에 따라 결과가 달라져요.

Agent SDK는 그 도구를 손에 쥔 직원을 고용하는 것에 가까워요. "이 업무 처리해줘"라고 하면, 직원이 알아서 필요한 도구를 꺼내고, 중간에 판단하고, 예상치 못한 상황에 대응하면서 결과물을 가져오는 거죠. 저는 결과만 받으면 돼요.

물론 이 "직원"이 무슨 판단을 했는지, 어떤 도구를 썼는지는 로그로 볼 수 있어요. 그래서 블랙박스처럼 무섭지는 않고요.

구체적으로 어떤 구조로 돌아가냐면

Claude Agent SDK는 크게 세 가지 개념 위에 얹혀 있어요.

첫 번째는 도구(Tool)예요. AI가 사용할 수 있는 기능들이에요. 웹 검색, 코드 실행, 파일 읽기, 외부 API 호출 같은 것들이죠. 개발자가 직접 만들어서 붙일 수도 있고, SDK에서 기본 제공하는 것도 있어요. 참고로 이 도구를 AI에게 "어떻게 쓰는지" 알려주는 방식이 함수 호출(Function Calling)인데, Agent SDK는 그 위에서 동작한다고 보면 이해가 빨라요.

두 번째는 루프(Loop)예요. AI가 한 번 답하고 끝나는 게 아니라, "지금 뭘 할지 판단 → 도구 실행 → 결과 확인 → 다음 판단"을 반복하는 구조예요. 이 루프가 Agent를 Agent답게 만들어주는 부분이에요.

세 번째는 상태(State) 관리예요. 작업이 여러 단계에 걸쳐 있으니, 이전에 뭘 했는지 기억하고 있어야 하잖아요. SDK가 그 맥락을 들고 다니면서 Claude에게 전달해줘요.

그래서 이걸로 뭘 만드는 건데

가장 현실적인 예시를 들어볼게요.

직장 동료가 "우리 팀 보고서 자동화할 수 없을까?" 하고 물어본 적 있어요. 매주 월요일마다 구글 시트에서 지난주 수치 뽑고, 전주 대비 증감 계산하고, 슬랙에 요약 올리는 게 30분짜리 반복 작업이라고요.

Claude API만 써도 "이 데이터 요약해줘"는 가능해요. 근데 "시트 자동으로 열고 → 데이터 읽고 → 계산하고 → 슬랙 보내기"는 연결고리가 없어요. Agent SDK가 바로 그 연결고리 역할을 해요. 각 단계를 Tool로 만들어 붙이면, 월요일 아침에 알아서 돌고 슬랙에 메시지가 올라와 있는 걸 보게 돼요.

다른 쪽으로는 고객지원 자동화, 코드 리뷰 파이프라인, 리서치 보조 도구 같은 것들도 많이 만들고 있어요. 공통점은 "여러 단계가 순서대로 이어지고, 중간에 판단이 필요한 작업"이라는 거예요.

입문자가 걸리는 포인트, 미리 알아두면 덜 헤매요

SDK를 처음 건드릴 때 저도 몇 가지에서 막혔어요.

일단 루프가 무한히 돌 수 있어요. 생각보다 자주 생기는 상황인데, AI가 어떤 이유로든 작업을 끝낼 시점을 못 잡으면 계속 돌면서 토큰을 써요. "최대 몇 번까지만 돌아라"는 제한을 처음부터 설정해두는 게 좋아요. 토큰 비용 쪽으로는 이미 요금 구조를 한 번 훑어두는 것도 도움이 돼요. Agent 기반 앱은 API 단건 호출보다 토큰이 훨씬 빠르게 쌓이거든요.

두 번째는 디버깅이에요. 단순 API는 요청-응답이 명확하니까 뭐가 잘못됐는지 바로 보여요. 에이전트는 중간 단계가 여러 개라서 어느 시점에서 틀어졌는지 찾는 게 처음엔 막막해요. SDK에서 제공하는 로그를 적극적으로 찍어두는 습관을 들이는 게 나중에 시간을 많이 아껴줘요.

세 번째는 Tool 설계예요. 도구를 너무 크게 만들면 AI가 어디에 어떻게 써야 하는지 헷갈려해요. "이 Tool은 딱 이것만 한다"는 단일 책임 원칙, 코드 짤 때랑 똑같이 적용하면 돼요.

지금 당장 써야 하나, 아니면 좀 더 지켜봐야 하나

솔직한 얘기 하면, 아직 배우는 중이에요. Anthropic이 계속 업데이트를 내고 있고, 문서도 자주 바뀌어요. 그래서 "다 완성됐으니 써라"는 느낌보다는 "같이 만들어가는 중"에 가까워요.

근데 그게 입문자한테 꼭 나쁜 건 아니에요. 지금 익혀두면, 나중에 안정화됐을 때 남들보다 훨씬 빠르게 활용할 수 있거든요. 저는 "완벽하게 익히고 쓰자"보다 "일단 작은 거 하나 만들어보자"는 쪽이 훨씬 효과적이었어요. 슬랙 알림 하나, 파일 요약 하나, 거기서부터 시작하면 구조가 몸으로 이해돼요.

복잡한 멀티 에이전트 구조나 보안 이슈는 그다음 얘기예요. 일단 한 에이전트가 두세 가지 도구를 써서 작업 하나를 마치는 것, 그것부터 만들어보는 게 순서예요.

📌 한 줄 정리: Claude Agent SDK는 "AI가 여러 단계 작업을 스스로 판단하며 처리하게 해주는 틀"이에요. API가 질문 하나에 답 하나라면, SDK는 도구들을 넘나들며 연속 작업을 완료하는 구조예요. 토큰 루프 제한과 Tool 설계만 처음부터 잡아두면, 생각보다 빠르게 뭔가 돌아가는 걸 만들 수 있어요.