지난해 우리는 고객들과 함께 쌓아온 효과적인 에이전트 구축 경험을 공유한 바 있습니다. 이후 Anthropic 내부의 개발자 생산성 향상을 위해 만들었던 에이전틱 코딩 솔루션, Claude Code를 공식 출시했습니다.
지난 몇 달간 Claude Code는 단순한 코딩 도구를 훨씬 넘어서는 존재로 성장했습니다. Anthropic에서는 심층 리서치, 영상 제작, 노트 정리 등 코딩 외의 수많은 용도로 Claude Code를 활용해 왔습니다. 실제로 사내 주요 에이전트 루프 대부분이 이미 Claude Code 기반으로 운영되고 있습니다.
다시 말해, Claude Code를 구동하는 에이전트 하네스(Claude Code SDK)는 다양한 유형의 에이전트에도 동일하게 적용할 수 있습니다. 이러한 확장된 비전을 반영해, Claude Code SDK의 이름을 Claude Agent SDK로 변경합니다.
이 글에서는 Claude Agent SDK를 만든 이유, 이를 활용해 나만의 에이전트를 구축하는 방법, 그리고 우리 팀이 실제 배포 과정에서 발견한 모범 사례를 소개합니다.
Claude에게 컴퓨터를 주다
Claude Code의 핵심 설계 원칙은 간단합니다. Claude에게 프로그래머가 매일 쓰는 것과 동일한 도구를 제공하는 것입니다. 코드베이스에서 적절한 파일을 찾고, 파일을 작성하고 편집하며, 코드를 린트하고, 실행하고, 디버깅하고, 수정하는 과정을 코드가 성공할 때까지 반복적으로 수행할 수 있어야 합니다.
터미널을 통해 사용자의 컴퓨터에 접근할 수 있게 하자, Claude는 프로그래머와 동일한 방식으로 코드를 작성할 수 있게 되었습니다.
그런데 이 접근 방식 덕분에 Claude Code의 Claude는 비(非)코딩 작업에서도 뛰어난 성능을 발휘합니다. bash 명령 실행, 파일 편집·생성·검색 도구를 갖추면 Claude는 CSV 파일을 읽고, 웹을 검색하고, 시각화를 만들고, 지표를 해석하는 등 다양한 디지털 작업을 수행할 수 있습니다. 한마디로 컴퓨터를 활용하는 범용 에이전트를 만들 수 있는 것입니다. Claude Agent SDK의 핵심 설계 원칙은 에이전트에게 컴퓨터를 제공해 사람처럼 일할 수 있게 하는 것입니다.
새로운 유형의 에이전트 만들기
Claude에게 컴퓨터를 주면 기존보다 훨씬 효과적인 에이전트를 구축할 수 있다고 믿습니다. 예를 들어, 우리 SDK로 개발자들이 만들 수 있는 에이전트는 다음과 같습니다:
- 금융 에이전트: 사용자의 포트폴리오와 목표를 파악하고, 외부 API에 접근하여 데이터를 저장하고 코드를 실행해 계산을 수행함으로써 투자 평가를 돕는 에이전트를 구축할 수 있습니다.
- 개인 비서 에이전트. 여행 예약, 일정 관리, 약속 잡기, 브리핑 자료 작성 등 다양한 업무를 수행하는 에이전트를 만들 수 있습니다. 내부 데이터 소스에 연결하고 여러 애플리케이션에 걸쳐 맥락을 추적할 수 있습니다.
- 고객 지원 에이전트: 고객 서비스 티켓처럼 모호성이 높은 사용자 요청을 처리하는 에이전트를 만들 수 있습니다. 사용자 데이터를 수집·검토하고, 외부 API에 연결하며, 사용자에게 답변을 보내고, 필요시 담당자에게 에스컬레이션할 수 있습니다.
- 심층 리서치 에이전트: 대규모 문서 컬렉션을 대상으로 종합적인 리서치를 수행하는 에이전트를 만들 수 있습니다. 파일 시스템을 탐색하고, 여러 출처의 정보를 분석·종합하며, 파일 간 데이터를 교차 검증하고, 상세한 보고서를 생성합니다.
이 외에도 가능성은 무궁무진합니다. SDK는 자동화하려는 워크플로우가 무엇이든 에이전트를 구축할 수 있는 핵심 프리미티브를 제공합니다.
에이전트 루프 구축하기
Claude Code에서 Claude는 보통 다음과 같은 피드백 루프로 동작합니다: 컨텍스트 수집 → 행동 실행 → 결과 검증 → 반복.
이 루프는 다른 에이전트를 설계할 때도 유용한 사고 프레임워크가 됩니다. 에이전트에 어떤 역량을 부여해야 하는지 판단하는 데 도움이 되기 때문입니다. 이를 구체적으로 설명하기 위해 Claude Agent SDK로 이메일 에이전트를 구축하는 예시를 살펴보겠습니다.
컨텍스트 수집
에이전트를 개발할 때는 프롬프트만 주는 것으로는 부족합니다. 에이전트가 스스로 컨텍스트를 가져오고 갱신할 수 있어야 합니다. SDK의 기능이 이를 어떻게 지원하는지 살펴보겠습니다.
에이전틱 검색과 파일 시스템
파일 시스템은 모델의 컨텍스트에 끌어올 수 있는 정보의 저장소 역할을 합니다.
Claude는 로그나 사용자 업로드 파일처럼 대용량 파일을 만나면 grep, tail 같은 bash 스크립트를 활용해 필요한 정보만 컨텍스트에 불러오는 방식을 스스로 결정합니다. 본질적으로 에이전트의 폴더·파일 구조 자체가 일종의 컨텍스트 엔지니어링이 되는 셈입니다.
이메일 에이전트라면 'Conversations' 폴더에 이전 대화를 저장해 둘 수 있습니다. 이렇게 하면 사용자가 이전 대화에 대해 물었을 때 해당 폴더를 검색하여 필요한 컨텍스트를 확보할 수 있습니다.
시맨틱 검색
시맨틱 검색은 에이전틱 검색보다 빠르지만, 정확도가 낮고, 유지보수가 어려우며, 투명성도 떨어집니다. 관련 컨텍스트를 '청크'로 나누고, 이를 벡터로 임베딩한 뒤, 해당 벡터에 쿼리를 날려 개념을 검색하는 방식입니다. 이러한 한계를 감안해 에이전틱 검색부터 시작하고, 더 빠른 결과나 더 다양한 변형이 필요한 경우에만 시맨틱 검색을 추가하는 것을 권장합니다.
서브에이전트
Claude Agent SDK는 서브에이전트를 기본으로 지원합니다. 서브에이전트가 유용한 이유는 크게 두 가지입니다. 첫째, 병렬 처리가 가능합니다. 여러 서브에이전트를 동시에 실행하여 각각 다른 작업을 처리할 수 있습니다. 둘째, 컨텍스트 관리에 효과적입니다. 서브에이전트는 독립된 컨텍스트 윈도우를 사용하며, 전체 컨텍스트가 아닌 관련 정보만 오케스트레이터에 반환합니다. 따라서 대량의 정보 중 극히 일부만 유용한 작업에 특히 적합합니다.
이메일 에이전트를 설계할 때 '검색 서브에이전트' 기능을 부여할 수 있습니다. 이메일 에이전트가 여러 검색 서브에이전트를 병렬로 실행하면, 각각 다른 쿼리로 이메일 기록을 검색한 뒤 전체 이메일 스레드 대신 관련 발췌 내용만 반환하게 됩니다.
압축(Compaction)
에이전트가 장시간 실행될 때 컨텍스트 관리는 매우 중요합니다. Claude Agent SDK의 compact 기능은 컨텍스트 한도에 가까워지면 이전 메시지를 자동으로 요약해 컨텍스트가 부족해지는 상황을 방지합니다. 이 기능은 Claude Code의 compact 슬래시 명령을 기반으로 합니다.
행동 실행
컨텍스트를 확보했다면, 이제 에이전트가 유연하게 행동할 수 있는 방법을 제공해야 합니다.
도구(Tools)
도구는 에이전트가 실행하는 가장 기본적인 빌딩 블록입니다. 도구는 Claude의 컨텍스트 윈도우에서 높은 비중을 차지하므로, 작업 수행 방법을 결정할 때 Claude가 가장 먼저 고려하는 행동이 됩니다. 따라서 컨텍스트 효율성을 극대화할 수 있도록 도구 설계에 신경을 써야 합니다. 더 자세한 모범 사례는 블로그 포스트 에이전트를 위한(그리고 에이전트와 함께 작성하는) 효과적인 도구 설계에서 확인할 수 있습니다.
따라서 도구에는 에이전트가 수행해야 할 핵심 행동을 정의해야 합니다. Claude Agent SDK에서 커스텀 도구를 만드는 방법을 알아보세요.
이메일 에이전트라면 "fetchInbox"나 "searchEmails"처럼 가장 빈번하게 수행하는 핵심 행동을 도구로 정의할 수 있습니다.
Bash 및 스크립트
Bash는 에이전트가 컴퓨터를 활용해 유연하게 작업을 수행할 수 있게 해주는 범용 도구로 유용합니다.
이메일 에이전트의 경우, 사용자의 첨부 파일에 중요한 정보가 담겨 있을 수 있습니다. Claude는 아래와 같이 코드를 작성해 PDF를 다운로드하고, 텍스트로 변환한 뒤, 그 안에서 유용한 정보를 검색할 수 있습니다:
코드 생성
Claude Agent SDK는 코드 생성에 특히 강합니다. 이유가 있습니다. 코드는 정밀하고, 조합이 가능하며, 무한히 재사용할 수 있어, 복잡한 작업을 안정적으로 수행해야 하는 에이전트에 이상적인 출력 형태입니다.
에이전트를 구축할 때 "어떤 작업을 코드로 표현하면 더 효과적일까?"라는 질문을 던져 보세요. 이 질문에 대한 답이 종종 에이전트의 역량을 크게 확장시킵니다.
예를 들어, 최근 출시한 Claude.AI의 파일 생성 기능은 전적으로 코드 생성에 기반합니다. Claude가 Python 스크립트를 작성해 Excel 스프레드시트, PowerPoint 프레젠테이션, Word 문서를 생성하며, 다른 방식으로는 구현하기 어려운 일관된 서식과 복잡한 기능을 제공합니다.
이메일 에이전트에서 사용자가 수신 이메일에 대한 규칙을 만들 수 있게 하고 싶다면, 해당 이벤트가 발생했을 때 실행할 코드를 작성하는 방식으로 구현할 수 있습니다:
MCP
Model Context Protocol(MCP)은 외부 서비스와의 표준화된 통합을 제공하며, 인증과 API 호출을 자동으로 처리합니다. 커스텀 통합 코드를 직접 작성하거나 OAuth 플로우를 관리하지 않아도 Slack, GitHub, Google Drive, Asana 같은 도구에 에이전트를 연결할 수 있습니다.
이메일 에이전트에서 팀 맥락을 파악하기 위해 search Slack messages하거나, 고객 요청에 이미 담당자가 배정되었는지 확인하기 위해 check Asana tasks할 수 있습니다. MCP 서버를 사용하면 이런 통합이 바로 동작합니다. 에이전트가 search_slack_messages나 get_asana_tasks 같은 도구를 호출하기만 하면 나머지는 MCP가 알아서 처리합니다.
MCP 생태계가 빠르게 성장하면서 사전 구축된 통합이 계속 늘어나고 있어, 새로운 역량을 에이전트에 신속하게 추가할 수 있습니다. 덕분에 에이전트의 행동 설계에 더 집중할 수 있습니다.
결과 검증
Claude Code SDK는 작업 결과를 평가하는 단계로 에이전트 루프를 완성합니다. 자신의 출력을 스스로 점검하고 개선할 수 있는 에이전트는 근본적으로 더 신뢰할 수 있습니다. 오류가 누적되기 전에 잡아내고, 방향이 틀어지면 스스로 교정하며, 반복할수록 품질이 향상됩니다.
핵심은 Claude가 자신의 결과물을 구체적으로 평가할 수 있는 수단을 제공하는 것입니다. 우리가 효과적이라고 확인한 세 가지 접근 방식을 소개합니다:
규칙 정의
가장 좋은 피드백 형태는 출력에 대한 명확한 규칙을 정의하고, 어떤 규칙을 왜 위반했는지 설명하는 것입니다.
코드 린팅은 규칙 기반 피드백의 훌륭한 사례입니다. 피드백이 상세할수록 효과는 커집니다. 예를 들어, 순수 JavaScript 대신 TypeScript를 생성하고 린트하면 여러 추가 피드백 계층을 확보할 수 있어 일반적으로 더 효과적입니다.
이메일을 생성할 때 Claude가 이메일 주소의 유효성을 확인하고(유효하지 않으면 오류 발생), 사용자가 해당 주소로 이전에 이메일을 보낸 적이 있는지 확인하도록(있으면 경고 발생) 할 수 있습니다.
시각적 피드백
UI 생성이나 테스트처럼 시각적 작업에 에이전트를 활용할 때는 스크린샷이나 렌더링 결과 형태의 시각적 피드백이 유용합니다. 예를 들어, HTML 서식이 적용된 이메일을 보내기 전에 생성된 이메일의 스크린샷을 찍어 모델에 다시 제공하면 시각적 검증과 반복적 개선이 가능합니다. 모델은 시각적 결과물이 요청사항과 일치하는지 확인합니다.
구체적으로 다음 항목을 점검합니다:
- 레이아웃 - 요소의 위치가 올바른지, 간격이 적절한지
- 스타일링 - 색상, 폰트, 서식이 의도한 대로 표시되는지
- 콘텐츠 계층 구조 - 정보가 적절한 순서와 강조로 표현되는지
- 반응형 - 깨지거나 답답해 보이는 부분이 있는지 (단, 단일 스크린샷만으로는 뷰포트 정보가 제한적)
Playwright 같은 MCP 서버를 활용하면 이 시각적 피드백 루프를 자동화할 수 있습니다. 렌더링된 HTML의 스크린샷을 찍고, 다양한 뷰포트 크기를 캡처하며, 인터랙티브 요소까지 테스트하는 것까지 모두 에이전트 워크플로우 안에서 처리할 수 있습니다.
LLM을 심사위원으로 활용
다른 언어 모델이 에이전트의 출력을 모호한 규칙 기준으로 "심사"하게 할 수도 있습니다. 일반적으로 매우 견고한 방법은 아니며, 지연 시간도 상당히 증가할 수 있지만, 약간의 성능 향상이라도 비용 대비 가치가 있는 애플리케이션에서는 도움이 됩니다.
이메일 에이전트라면 별도의 서브에이전트가 초안의 어조를 심사하여, 사용자가 이전에 보낸 메시지의 톤과 잘 맞는지 확인하게 할 수 있습니다.
에이전트 테스트 및 개선
에이전트 루프를 몇 차례 반복한 뒤에는 에이전트를 테스트하고, 주어진 작업에 충분히 대비되어 있는지 확인하는 것을 권장합니다. 에이전트를 개선하는 가장 좋은 방법은 출력 결과, 특히 실패한 사례를 꼼꼼히 살펴보고, 에이전트의 입장에서 생각해 보는 것입니다. 이 작업을 위한 적절한 도구를 갖추고 있는가?
에이전트가 맡은 역할을 제대로 수행할 준비가 되었는지 평가할 때 다음 질문들을 던져 보세요:
- 에이전트가 작업을 잘못 이해한다면, 핵심 정보가 누락된 것일 수 있습니다. 검색 API의 구조를 변경해 필요한 정보를 더 쉽게 찾을 수 있게 할 수 있을까요?
- 에이전트가 특정 작업에서 반복적으로 실패한다면, 도구 호출에 명시적인 규칙을 추가해 해당 실패를 식별하고 수정할 수 있을까요?
- 에이전트가 오류를 스스로 수정하지 못한다면, 문제에 다른 방식으로 접근할 수 있는 더 유용하거나 창의적인 도구를 제공할 수 있을까요?
- 기능을 추가할수록 에이전트 성능이 불안정해진다면, 실제 고객 사용 패턴을 기반으로 대표적인 테스트 세트를 구성하여 프로그래매틱 평가(eval)를 수행하세요.
시작하기
Claude Agent SDK는 Claude에게 파일 작성, 명령 실행, 반복적 개선이 가능한 컴퓨터 환경을 제공함으로써 자율 에이전트 구축을 한층 쉽게 만들어 줍니다.
에이전트 루프(컨텍스트 수집, 행동 실행, 결과 검증)를 염두에 두면, 배포와 반복 개선이 용이한 안정적인 에이전트를 구축할 수 있습니다.
지금 바로 Claude Agent SDK를 시작해 보세요. 이미 SDK 기반으로 개발 중인 분들은 이 가이드를 참고하여 최신 버전으로 마이그레이션하시기 바랍니다.
감사의 글
Thariq Shihipar가 작성하고, Molly Vorwerck, Suzanne Wang, Alex Isken, Cat Wu, Keir Bradwell, Alexander Bricken, Ashwin Bhat이 검토 및 편집에 참여했습니다.
