요약: Anthropic은 Claude Code SDK를 Claude Agent SDK로 개명하고 더 넓은 비전을 반영합니다. 이 SDK는 개발자가 다양한 유형의 자율형 에이전트를 구축할 수 있도록 Claude에게 컴퓨터 접근 권한을 부여합니다. 에이전트 루프(컨텍스트 수집 → 작업 수행 → 작업 검증 → 반복)를 따라 개발자는 재무, 개인 비서, 고객 지원, 심층 연구 등 다양한 에이전트를 만들 수 있습니다.
작년에 우리는 고객들과 함께 효과적인 에이전트 구축에 대한 교훈을 공유했습니다. 그 이후로 우리는 Anthropic에서 개발자 생산성을 지원하기 위해 원래 구축한 에이전트형 코딩 솔루션인 Claude Code를 출시했습니다. 지난 몇 달 동안 Claude Code는 코딩 도구를 훨씬 넘어서는 것이 되었습니다. Anthropic에서 우리는 이를 심층 연구, 비디오 제작, 메모 작성 등 수많은 비코딩 애플리케이션에 사용하고 있습니다. 사실 이제는 거의 모든 주요 에이전트 루프를 구동하기 시작했습니다. 즉, 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는 기본적으로 서브에이전트를 지원합니다. 서브에이전트는 두 가지 주요 이유로 유용합니다. 첫째, 병렬화를 활성화합니다. 동시에 다른 작업에 대해 작업하는 여러 서브에이전트를 실행할 수 있습니다. 둘째, 컨텍스트 관리를 돕습니다. 서브에이전트는 자체 격리된 컨텍스트 윈도우를 사용하며 전체 컨텍스트가 아닌 관련 정보만 오케스트레이터에게 다시 보냅니다. 이는 대부분의 정보가 유용하지 않은 대량의 정보를 처리해야 하는 작업에 이상적입니다. 이메일 에이전트를 설계할 때 ‘검색 서브에이전트’ 기능을 제공할 수 있습니다. 그러면 이메일 에이전트는 병렬로 여러 검색 서브에이전트를 실행할 수 있습니다. 각각은 이메일 기록에 대해 다른 쿼리를 실행하고 전체 이메일 스레드가 아닌 관련 발췌 부분만 반환합니다.
압축
에이전트가 장기간 실행되는 경우 컨텍스트 유지 관리가 중요해집니다. Claude Agent SDK의 압축 기능은 컨텍스트 제한에 접근할 때 이전 메시지를 자동으로 요약하므로 에이전트가 컨텍스트 부족 현상을 겪지 않습니다. 이는 Claude Code의 compact 슬래시 명령을 기반으로 합니다.
작업 수행
컨텍스트를 수집했으면 에이전트가 유연하게 작업을 수행할 수 있는 방법을 제공하고 싶을 것입니다.
도구(Tools)
도구는 에이전트를 위한 실행의 주요 구성 요소입니다. 도구는 Claude의 컨텍스트 윈도우에서 두드러지며 Claude가 작업을 완료하는 방법을 결정할 때 고려하는 주요 작업이 됩니다. 즉, 컨텍스트 효율성을 극대화하기 위해 도구를 설계하는 방법에 대해 인식해야 합니다. 우리의 블로그 게시물 Writing effective tools for agents – with agents에서 더 많은 모범 사례를 볼 수 있습니다. 따라서 도구는 에이전트가 수행하기를 원하는 주요 작업이어야 합니다. Claude Agent SDK에서 사용자 정의 도구를 만드는 방법을 알아보세요. 이메일 에이전트의 경우 “fetchInbox” 또는 “searchEmails”와 같은 도구를 에이전트의 주요이고 가장 빈번한 작업으로 정의할 수 있습니다.
Bash 및 스크립트
Bash는 컴퓨터를 사용하여 유연한 작업을 수행할 수 있도록 에이전트를 위한 범용 도구로 유용합니다. 이메일 에이전트에서 사용자는 첨부파일에 중요한 정보를 저장할 수 있습니다. Claude는 아래와 같이 호출하여 PDF를 다운로드하고 텍스트로 변환하고 유용한 정보를 찾기 위해 검색하는 코드를 작성할 수 있습니다.
코드 생성
Claude Agent SDK는 코드 생성에 탁월합니다. 그리고 그럴만한 이유가 있습니다. 코드는 정확하고 구성 가능하며 무한히 재사용 가능하여 복잡한 작업을 신뢰할 수 있게 수행해야 하는 에이전트에 이상적인 출력입니다. 에이전트를 구축할 때 다음을 고려하세요: 코드로 표현하는 것이 이로운 작업은 무엇입니까? 종종 대답은 상당한 기능을 해제합니다. 예를 들어, Claude.AI의 최근 파일 생성 출시는 완전히 코드 생성에 의존합니다. Claude는 엑셀 스프레드시트, PowerPoint 프레젠테이션 및 Word 문서를 만드는 Python 스크립트를 작성하여 다른 방법으로 달성하기 어려운 일관된 서식 지정과 복잡한 기능을 보장합니다. 이메일 에이전트에서 인바운드 이메일에 대한 규칙을 사용자가 생성할 수 있도록 하고 싶을 수 있습니다. 이를 달성하기 위해 해당 이벤트에서 실행할 코드를 작성할 수 있습니다.
MCPs
모델 컨텍스트 프로토콜(MCP)은 인증 및 API 호출을 자동으로 처리하는 외부 서비스에 대한 표준화된 통합을 제공합니다. 즉, 사용자 정의 통합 코드를 작성하거나 OAuth 흐름을 직접 관리하지 않고도 Slack, GitHub, Google Drive 또는 Asana와 같은 도구에 에이전트를 연결할 수 있습니다. 이메일 에이전트의 경우 팀 컨텍스트를 이해하기 위해 Slack 메시지를 검색하거나 누군가 고객 요청을 처리하도록 할당되었는지 확인하기 위해 Asana 작업을 확인하고 싶을 수 있습니다. MCP 서버를 사용하면 이러한 통합이 즉시 작동합니다. 에이전트는 search_slack_messages 또는 get_asana_tasks와 같은 도구를 호출하기만 하면 MCP가 나머지를 처리합니다. 성장하는 MCP 생태계는 사전 구축된 통합을 사용할 수 있게 되면 에이전트에 새로운 기능을 빠르게 추가할 수 있으므로 에이전트 동작에 집중할 수 있습니다.
작업 검증
Claude Code SDK는 자신의 작업을 평가하여 에이전트 루프를 완료합니다. 출력을 확인하고 개선할 수 있는 에이전트는 근본적으로 더 신뢰할 수 있습니다. 실수가 합산되기 전에 잡고, 드리프트할 때 자체 수정하고, 반복할 때 개선됩니다. 핵심은 Claude에게 작업을 평가할 수 있는 구체적인 방법을 제공하는 것입니다. 우리가 효과적이라고 발견한 세 가지 접근 방식은 다음과 같습니다.
규칙 정의
피드백의 가장 좋은 형태는 출력에 대해 명확하게 정의된 규칙을 제공한 다음 어떤 규칙이 실패했는지와 그 이유를 설명하는 것입니다. 코드 린팅은 규칙 기반 피드백의 훌륭한 형태입니다. 피드백이 더 깊을수록 더 좋습니다. 예를 들어, 순수 JavaScript를 생성하는 것보다 TypeScript를 생성하고 린팅하는 것이 일반적으로 더 좋습니다. 이는 여러 추가 피드백 레이어를 제공하기 때문입니다. 이메일을 생성할 때 Claude가 이메일 주소가 유효한지 확인(그렇지 않으면 오류 발생)하고 사용자가 이전에 그들에게 이메일을 보냈는지 확인(그렇다면 경고 발생)하고 싶을 수 있습니다.
시각적 피드백
UI 생성이나 테스트와 같은 시각적 작업을 완료하기 위해 에이전트를 사용할 때 스크린샷 또는 렌더 형태의 시각적 피드백이 도움이 될 수 있습니다. 예를 들어, HTML 서식으로 이메일을 보내는 경우 생성된 이메일의 스크린샷을 찍어 모델에 다시 제공하여 시각적 확인 및 반복적 개선을 할 수 있습니다. 그러면 모델이 시각적 출력이 요청한 것과 일치하는지 확인합니다. 예를 들어:
- 레이아웃 – 요소가 올바르게 배치되었는가? 간격이 적절한가?
- 스타일링 – 색상, 글꼴 및 서식이 의도한 대로 나타나는가?
- 콘텐츠 계층 구조 – 정보가 올바른 순서로 적절한 강조와 함께 제시되는가?
- 반응형 – 깨지거나 좁아 보이는가? (단일 스크린샷에는 뷰포트 정보가 제한적)
Playwright와 같은 MCP 서버를 사용하면 이 시각적 피드백 루프를 자동화할 수 있습니다. 렌더링된 HTML의 스크린샷을 찍고, 다양한 뷰포트 크기를 캡처하고, 대화형 요소를 테스트하는 등 모든 에이전트 워크플로우 내에서 수행할 수 있습니다. 대규모 언어 모델(LLM)의 시각적 피드백은 에이전트에 유용한 지침을 제공할 수 있습니다.
판사로서의 LLM
또 다른 언어 모델이 퍼지 규칙에 따라 에이전트의 출력을 “판단”하게 할 수도 있습니다. 이것은 일반적으로 매우 강력한 방법은 아니며 상당한 대기 시간 트레이드오프가 있을 수 있지만 성능의 향상이 비용치고 가치 있는 애플리케이션에서는 도움이 될 수 있습니다. 이메일 에이전트에는 사용자의 이전 메시지와 잘 어울리는지 확인하기 위해 초안의 어조를 판단하는 별도의 서브에이전트가 있을 수 있습니다.
에이전트 테스트 및 개선
에이전트 루프를 몇 번 거친 후 에이전트를 테스트하고 작업에 잘 갖추어져 있는지 확인하는 것이 좋습니다. 에이전트를 개선하는 가장 좋은 방법은 출력을 주의 깊게 살펴보는 것입니다. 특히 실패한 사례를 보고 그 입장이 되어보세요: 작업에 올바른 도구가 있습니까? 에이전트가 작업을 잘 수행할 수 있는지 여부를 평가할 때 묻는 다른 질문은 다음과 같습니다:
- 에이전트가 작업을 오해하는 경우 중요한 정보가 누락되었을 수 있습니다. 필요한 정보를 더 쉽게 찾을 수 있도록 검색 API의 구조를 변경할 수 있습니까?
- 에이전트가 작업에서 반복적으로 실패하는 경우 도구 호출에 실패를 식별하고 수정하는 공식 규칙을 추가할 수 있습니까?
- 에이전트가 오류를 수정할 수 없는 경우 문제를 다르게 접근할 수 있는 더 유용하거나 창의적인 도구를 제공할 수 있습니까?
- 기능을 추가할 때 에이전트의 성능이 달라지면 고객 사용을 기반으로 프로그래밍 평가(evals)를 위한 대표적인 테스트 세트를 구축하세요.
시작하기
Claude Agent SDK는 Claude에게 파일을 작성하고, 명령을 실행하고, 작업을 반복할 수 있는 컴퓨터에 대한 접근 권한을 제공하여 자율형 에이전트를 더 쉽게 구축할 수 있게 합니다. 에이전트 루프(컨텍스트 수집, 작업 수행, 작업 검증)를 염두에 두고 배포 및 반복이 쉬운 신뢰할 수 있는 에이전트를 구축할 수 있습니다. 오늘 Claude Agent SDK를 시작할 수 있습니다. 이미 SDK에서 구축 중인 개발자의 경우 이 가이드를 따라 최신 버전으로 마이그레이션하는 것이 좋습니다.
감사의 말씀
Thariq Shihipar가 작성했으며 Molly Vorwerck, Suzanne Wang, Alex Isken, Cat Wu, Keir Bradwell, Alexander Bricken 및 Ashwin Bhat의 노트와 편집이 포함되었습니다.
핵심 포인트
- Claude Agent SDK는 Claude에게 컴퓨터 접근 권한을 부여하여 다양한 자율형 에이전트를 구축할 수 있는 도구입니다.
- 에이전트 루프(컨텍스트 수집 → 작업 수행 → 작업 검증 → 반복)는 신뢰할 수 있는 에이전트 설계의 핵심 프레임워크입니다.
- 도구 설계, MCP 통합, 그리고 다양한 피드백 메커니즘(규칙, 시각적 피드백, LLM 판단)이 에이전트 성능을 결정합니다.
