Claude Agent SDK로 에이전트 빌드하기(Building Agents with the Claude Agent SDK)
Anthropic은 작년에 고객과 함께 효과적인 에이전트 구축(Building Effective Agents)을 통해 배운 점(Lesson)들을 공유했습니다. 이후, Anthropic은 Anthropic 내 개발자 생산성을 지원하기 위해 처음 개발했던 에이전트 기반 코딩 솔루션인 Claude Code를 공개했습니다.
지난 몇 달 동안 Claude Code는 단순한 코딩 도구를 넘어섰습니다. Anthropic 내부에서는 이를 연구, 영상 제작, 노트 작성 등 수많은 코드 작성이 아닌 작업(Non-Coding Tasks)에 활용해왔습니다.
즉, Claude Code를 구동하는 에이전트 프레임워크인 Claude Code SDK는 다른 다양한 유형의 에이전트를 구동할 수도 있습니다. 이러한 더 넓은 비전을 반영하기 위해 Anthropic은 Claude Code SDK의 이름을 Claude Agent SDK로 변경하였습니다.
이번 글에서는 Claude Agent SDK를 만든 이유, SDK를 활용해 직접 에이전트를 만드는 방법, 그리고 Anthropic 내부 팀에서의 실제 배포 과정에서 나온 모범 사례들을 공유합니다.
Claude에게 컴퓨터 주기(Giving Claude a Computer)
Claude Code의 핵심 설계 원칙(The Key Design Principle)는 Claude가 프로그래머들이 매일 사용하는 것과 동일한 도구를 가져야 한다는 것입니다. 즉, 코드베이스 내 파일을 찾고, 파일을 작성·편집하며, 검수(Lint)를 실행하고, 코드를 실행하고, 디버그하고, 필요할 경우 반복적으로 이 과정을 수행할 수 있어야 합니다.
Anthropic은 Claude에게 (터미널을 통해) 사용자 컴퓨터에 접근할 수 있도록 해줌으로써 프로그래머처럼 코드를 작성할 수 있다는 것을 확인했습니다.
하지만 이것은 Claude Code에서 Claude가 코드 작성이 아닌 다른 작업을 수행하는 경우에도 효과적이었습니다. Bash 명령어 실행, 파일 생성·편집·검색 도구를 제공하면 Claude는 CSV 파일을 읽고, 웹을 검색하고, 시각화를 만들고, 지표(Metric)를 해석하는 등 다양한 디지털 작업을 수행할 수 있습니다. 즉, 컴퓨터를 갖춘 범용 에이전트를 만들 수 있습니다.
새로운 유형의 에이전트 만들기(Creating New Types of Agents)
Anthropic은 Claude에게 컴퓨터를 제공하는 것이 이전보다 훨씬 효과적인 에이전트 개발을 가능하게 한다고 믿습니다. 예를 들어 SDK를 사용하여 다음과 같은 에이전트들을 만들 수 있습니다:
- 금융 에이전트(Finance Agent): 포트폴리오와 목표를 이해하고, 외부 API에 접근하며, 데이터를 저장하고 실행하여 투자 평가를 돕는 에이전트
- 개인 비서 에이전트(Personal Assistant Agent): 여행 예약, 캘린더 관리, 일정 조율, 브리핑 준비 등을 수행하며 내부 데이터 소스와 연결하고 여러 애플리케이션 간 컨텍스트를 추적하는 에이전트
- 고객 지원 에이전트(Customer Support Agent): 고객 서비스 티켓과 같은 모호한 요청을 처리하기 위해 사용자 데이터를 수집·검토하고, 외부 API와 연결하며, 필요 시 메시지를 보내고 사람에게 확인이 필요함을 요청(Escalation)하는 에이전트
- 심층 연구 에이전트(Deep Research Agent): 대규모 문서 집합에서 파일 시스템 검색, 여러 출처의 정보 분석·통합, 데이터 교차 검증, 상세 보고서 생성 등을 수행하는 에이전트
즉, Claude Agent SDK는 원하는 워크플로우 자동화를 위한 기본적인 도구(Primitive)들을 제공합니다.
에이전트 루프 빌드하기(Building your agent loop)
Claude Code에서 Claude는 종종 다음과 같은 피드백 루프를 따릅니다:
컨텍스트 수집(Gather Context) → 액션 수행(Take Action) → 결과 검증(Verify Your Work) → 반복(Repeat)
이러한 루프는 다른 유형의 에이전트와 그들이 가져야 할 기능을 설계할 때에도 유용합니다. 이를 보여주기 위해 Claude Agent SDK로 이메일 에이전트를 만드는 예시를 살펴보겠습니다.
컨텍스트 수집(Gather Context)
에이전트를 개발할 때는 단순히 프롬프트만 제공하는 것이 아니라, 스스로 컨텍스트를 가져오고 갱신할 수 있어야 합니다. 이를 위해 SDK의 기능을 활용할 수 있습니다.
에이전트 기반 검색과 파일 시스템(Agentic search and the file system)
파일 시스템은 모델의 문맥(Context)에 불러올 수 있는 정보를 나타냅니다. Claude는 로그 파일이나 업로드된 대형 파일과 같은 데이터를 다룰 때 grep 및 tail 같은 bash 스크립트를 활용해 어떤 방식으로 컨텍스트에 적재할지를 결정합니다. 즉, 에이전트의 폴더 및 파일 구조 자체가 일종의 문맥 엔지니어링(Context Engineering)이 됩니다.
예를 들어 이메일 에이전트는 이전 대화를 Conversations라는 폴더에 저장해두고, 요청 시 이를 검색하여 컨텍스트로 활용할 수 있습니다.
의미 기반 검색(Semantic Search)
의미 기반 검색(Semantic Search)은 일반적으로 에이전트 기반 검색보다 빠르지만, 정확성은 낮고 유지 관리가 어렵고 투명성이 떨어집니다. 의미 기반 검색은 관련 컨텍스트를 ‘덩어리(Chunk)’로 나눈 후, 이를 벡터로 임베딩하고, 질의(Query)를 통해 개념을 검색하는 방식입니다. 이러한 한계 때문에 Anthropic은 기본적으로 에이전트 기반 검색으로 시작하고, 더 빠른 결과나 다양한 변형이 필요할 경우에만 의미 기반 검색을 추가할 것을 권장합니다.
서브에이전트(Subagents)
Claude Agent SDK는 기본적으로 서브에이전트(Subagent)를 지원합니다. 서브에이전트는 크게 두 가지 이유에서 유용합니다.
첫째, 병렬화를 가능하게 합니다. 여러 서브에이전트를 동시에 실행시켜 각각 다른 작업을 병렬로 처리할 수 있습니다.
둘째, 컨텍스트 관리를 돕습니다. 서브에이전트는 각자의 독립된 컨텍스트 윈도우를 사용하고, 전체 컨텍스트 대신 관련 정보만 오케스트레이터에게 전달합니다. 따라서 방대한 양의 정보를 다루지만 그중 대부분은 불필요한 경우 이상적입니다.
예를 들어 이메일 에이전트에는 ‘검색 서브에이전트(Search Subagent)’ 기능을 줄 수 있습니다. 그러면 이메일 에이전트는 여러 검색 서브에이전트를 병렬로 실행시켜 이메일 기록에 대해 각각 다른 쿼리를 실행하고, 전체 스레드 대신 관련 발췌 부분만 반환할 수 있습니다.
압축(Compaction)
에이전트가 오랜 시간 실행될 경우, 컨텍스트 유지 관리가 매우 중요해집니다. Claude Agent SDK의 압축(Compact) 기능은 컨텍스트 제한(Context Limit)에 도달하면 이전 메시지를 자동으로 요약하여 에이전트가 컨텍스트를 잃지 않도록 합니다. 이는 Claude Code의 /compact 명령어를 기반으로 합니다.
액션 수행(Take action)
컨텍스트를 수집한 후에는 에이전트가 유연하게 행동할 수 있는 방법을 제공해야 합니다.
도구(Tools)
도구(Tools)는 에이전트 실행의 기본 구성 요소(Building Block)입니다. 도구는 Claude의 컨텍스트 윈도우에서 중요한 위치를 차지하며, Claude가 작업을 수행할 때 가장 먼저 고려하는 주요 액션이 됩니다. 따라서 도구 설계는 컨텍스트 효율성을 극대화할 수 있도록 신중해야 합니다.
도구 작성 모범 사례는 Writing effective tools for agents – with agents 글에서 더 자세히 확인할 수 있습니다.
즉, 도구는 에이전트가 수행해야 할 주요 액션이어야 합니다. Claude Agent SDK에서 사용자 정의 도구(custom tools)를 만드는 방법도 배울 수 있습니다.
예를 들어 이메일 에이전트라면 fetchInbox 또는 searchEmails 같은 도구를 정의해 가장 자주 사용하는 액션으로 둘 수 있습니다.
Bash & 스크립트(Bash & Scripts)
Bash는 에이전트가 컴퓨터를 활용해 유연하게 작업할 수 있도록 해주는 범용 도구입니다.
예를 들어 이메일 에이전트의 사용자에게 중요한 정보가 첨부 파일에 저장되어 있을 수 있습니다. Claude는 PDF를 다운로드하고 텍스트로 변환한 뒤, 그 안에서 유용한 정보를 검색하는 코드를 작성할 수 있습니다.
코드 생성(Code Generation)
Claude Agent SDK는 코드 생성에 강점을 가지고 있으며, 이는 타당한 이유가 있습니다. 코드는 정확하고 조합 가능하며 무한히 재사용 가능하기 때문에 복잡한 작업을 안정적으로 수행해야 하는 에이전트의 출력으로 이상적입니다.
에이전트를 만들 때는 어떤 작업을 코드로 표현하는 것이 더 효과적인지를 고려해야 합니다. 이 질문은 종종 중요한 능력 확장을 가능하게 합니다.
예를 들어 최근 출시된 Claude.AI에서의 파일 생성(file creation)은 전적으로 코드 생성에 의존합니다. Claude는 Python 스크립트를 작성하여 Excel 스프레드시트, PowerPoint 프레젠테이션, Word 문서를 생성합니다. 이렇게 하면 일관된 포맷과 복잡한 기능을 보장할 수 있습니다.
이메일 에이전트의 경우, 수신 이메일에 대한 규칙을 사용자가 만들 수 있도록 하고 싶을 수 있습니다. 이를 위해 이벤트 발생 시 실행될 코드를 작성할 수 있습니다.
MCP(MCPs)
모델 컨텍스트 프로토콜(Model Context Protocol, MCP)은 외부 서비스와의 표준화된 통합을 제공합니다. 인증 및 API 호출을 자동으로 처리하기 때문에 Slack, GitHub, Google Drive, Asana와 같은 도구에 직접 연결할 수 있으며, 별도의 통합 코드 작성이나 oAuth 흐름 관리가 필요하지 않습니다.
예를 들어 이메일 에이전트는 팀 컨텍스트를 이해하기 위해 Slack 메시지 검색(Search Slack Messages)을 실행하거나, 특정 고객 요청이 이미 담당자에게 할당되었는지 확인하기 위해 Asana 작업 확인(Check Asana Tasks)를 실행할 수 있습니다. MCP 서버 덕분에 이러한 통합은 즉시 동작합니다. 에이전트는 단순히 search_slack_messages 또는 get_asana_tasks 같은 도구를 호출하기만 하면 되고, MCP가 나머지를 처리합니다.
점점 확장되는 MCP 생태계를 활용하면 사전 구축된 통합을 빠르게 추가해 에이전트의 기능을 확장할 수 있으며, 개발자는 에이전트의 동작 설계에만 집중할 수 있습니다.
결과 검증(Verify Your Work)
Claude Code SDK는 작업 평가를 통해 에이전트 루프를 마무리합니다.
자신의 출력을 확인하고 개선할 수 있는 에이전트는 근본적으로 더 신뢰성이 높습니다. 이들은 실수를 누적하기 전에 발견하고, 벗어났을 때 스스로 수정하며, 반복할수록 점점 나아집니다.
핵심은 Claude에게 작업을 평가할 수 있는 구체적인 방법을 제공하는 것입니다. Anthropic에서 효과적이라고 확인한 세 가지 접근 방식을 소개합니다:
규칙 정의(Defining Rules)
가장 좋은 피드백 방식은 출력에 대해 명확하게 정의된 규칙을 제공하고, 어떤 규칙이 실패했는지와 그 이유를 설명하는 것입니다.
코드 검수(Code Linting)은 규칙 기반 피드백의 훌륭한 예입니다. 피드백이 깊을수록 더 좋습니다. 예를 들어, 순수 JavaScript를 생성하는 것보다 TypeScript를 생성하고 검수(Lint)를 하는 것이 더 낫습니다. 이렇게 하면 여러 추가적인 피드백 계층을 얻을 수 있기 때문입니다.
이메일을 생성할 때는, Claude에게 이메일 주소가 유효한지 확인(유효하지 않으면 오류 발생), 해당 사용자에게 이전에 이메일을 보낸 적이 있는지 확인(보낸 적이 있으면 경고 발생)하도록 할 수 있습니다.
시각적 피드백(Visual Feedback)
UI 생성이나 테스트와 같은 시각적 작업을 수행할 때는 스크린샷이나 렌더링 형태의 시각적 피드백이 유용할 수 있습니다.
예를 들어 HTML 포맷으로 이메일을 전송할 때, 생성된 이메일의 스크린샷을 모델에 제공하여 시각적으로 검증하고 반복적으로 개선할 수 있습니다.
모델은 시각적 출력이 요청된 내용과 일치하는지를 확인합니다. 예를 들어:
- 레이아웃(Layout): 요소가 올바르게 배치되어 있는가? 간격이 적절한가?
- 스타일링(Styling): 색상, 글꼴, 포맷이 의도한 대로 나타나는가?
- 콘텐츠 계층(Content Hierarchy): 정보가 올바른 순서로, 적절한 강조와 함께 표시되는가?
- 반응성(Responsiveness): 화면이 깨져 보이지 않는가? 혹은 공간이 너무 협소하지 않은가? (단, 단일 스크린샷은 Viewport 정보를 제한적으로만 제공)
Playwright 같은 MCP 서버를 사용하면, HTML 렌더링 결과의 스크린샷을 자동으로 캡처하고 다양한 뷰포트 크기를 테스트하며, 심지어 인터랙티브 요소까지 테스트하는 시각적 피드백 루프를 구현할 수 있습니다.
대규모 언어 모델(LLM)의 시각적 피드백은 에이전트에 유용한 지침을 제공할 수 있습니다.
LLM을 평가자로 활용하기(LLM as a Judge)
또 다른 대규모 언어 모델을 활용해 에이전트의 출력을 ‘평가(Judge)’하게 할 수도 있습니다. 이는 모호한 규칙을 기반으로 동작하며, 일반적으로는 매우 견고하지 않고 지연(latency)도 클 수 있습니다. 그러나 성능 향상이 조금이라도 가치 있는 경우에는 도움이 될 수 있습니다.
예를 들어, 이메일 에이전트는 별도의 서브에이전트를 활용하여 초안의 어조(Tone)가 사용자의 이전 메시지와 잘 어울리는지 평가하게 할 수 있습니다.
에이전트 테스트 및 개선(Testing and Improving Your Agent)
에이전트 루프를 몇 번 실행한 후에는 반드시 테스트를 수행하여 해당 에이전트가 맡은 작업에 충분히 적합한지 확인하는 것이 좋습니다.
에이전트를 개선하는 가장 좋은 방법은 출력물을 주의 깊게 살펴보고, 실패 사례를 검토한 뒤 에이전트의 입장에서 생각해보는 것입니다. 즉, 에이전트가 해당 작업을 수행하는 데 올바른 도구를 가지고 있는지를 자문해야 합니다.
에이전트 평가 시 스스로에게 물어볼 만한 질문은 다음과 같습니다:
- 에이전트가 작업을 오해한다면, 중요한 정보가 빠져 있을 수 있습니다. 검색 API 구조를 변경해 필요한 정보를 더 쉽게 찾을 수 있도록 할 수 있는가?
- 에이전트가 반복적으로 실패한다면, 실패를 식별하고 수정할 수 있는 공식 규칙을 도구 호출에 추가할 수 있는가?
- 에이전트가 오류를 고치지 못한다면, 문제에 접근할 수 있는 더 유용하거나 창의적인 도구를 제공할 수 있는가?
- 기능을 추가할수록 에이전트의 성능이 변한다면, 고객 사용 사례를 기반으로 한 대표적인 테스트 세트(eval)를 만들어 프로그램적으로 평가할 수 있는가?
시작하기(Getting started)
Claude Agent SDK는 Claude에게 컴퓨터 접근 권한을 부여하여 파일을 작성하고, 명령어를 실행하며, 작업을 반복할 수 있도록 하여 자율적인 에이전트를 더 쉽게 만들 수 있게 합니다.
에이전트 루프(컨텍스트 수집 → 액션 수행 → 결과 검증)를 염두에 두면, 안정적이고 배포 및 반복이 용이한 에이전트를 구축할 수 있습니다.
지금 바로 Claude Agent SDK를 시작할 수 있습니다.
이미 SDK를 기반으로 구축 중인 개발자는 마이그레이션 가이드를 따라 최신 버전으로 이전(Migration)하는 것을 권장합니다.
Anthropic의 'Claude Agent SDK로 에이전트 빌드하기' 블로그
Claude Agent SDK (이전의 Claude Code SDK) 문서
https://docs.claude.com/en/api/agent-sdk/overview
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 