Claude Agent SDK는 라이브러리로 제공되는 Claude Code입니다. Claude Code를 구동하는 에이전트와 동일한 에이전트를 프로그래밍 방식으로 생성한 다음, 코드로 실행할 수 있습니다. 반복적인 작업을 자동화된 워크플로우로 전환하고 Replit에 배포하세요. 이 튜토리얼에서는 Todoist 받은 편지함을 정리하는 에이전트를 만듭니다. 작업을 가져오고, 레이블을 적용하고, 프로젝트별로 정렬한 다음, 일정에 따라 실행되도록 배포합니다.Documentation Index
Fetch the complete documentation index at: https://docs.replit.com/llms.txt
Use this file to discover all available pages before exploring further.
배우게 될 내용
- Claude Agent SDK의 작동 방식과 사용 시점
- 핵심 구성 요소: 에이전트, 도구, MCP 서버, 스킬, 권한
- Integrations를 사용해 Replit에서 작업 자동화 에이전트 빌드하기
- 예약 배포로 에이전트를 일정에 따라 배포하기
사전 요구 사항
- Replit 계정 (배포용으로 Core 또는 Pro 플랜 권장)
- Anthropic API 키
- Todoist 계정 (또는 자동화하려는 다른 서비스)
Claude Agent SDK 작동 방식
에이전트는 루프입니다. 프롬프트를 보내면 에이전트가 실행할 도구를 선택하고, 결과를 확인하고, 작업이 완료될 때까지 이 과정을 반복합니다. 프롬프트는 여러분이 제공합니다. 루프는 SDK가 처리합니다. 하지만 SDK는 한 걸음 더 나아갑니다. 오케스트레이터 에이전트가 각자의 도구와 컨텍스트 윈도우를 가진 전문 하위 에이전트에게 작업을 위임하는 멀티 에이전트 아키텍처를 구축할 수 있습니다.핵심 구성 요소
| 구성 요소 | 역할 |
|---|---|
| 쿼리 루프 | 기반: 프롬프트 → 도구 선택 → 실행 → 확인 → 반복 |
| 에이전트 | 자체 도구와 지침을 가진 전문화된 구성 |
| 도구 | 에이전트가 수행할 수 있는 작업 — 명령 실행, API 호출, 파일 편집 |
| MCP 서버 | 도구 모음을 노출하는 외부 프로세스 (컨텍스트가 무거우며 처음에 로드됨) |
| 스킬 | 에이전트에게 작업 방법을 가르치는 마크다운 지침 파일 (컨텍스트 효율적, 필요 시 로드) |
| 권한 | 각 에이전트가 접근하고 실행할 수 있는 항목에 대한 세밀한 제어 |
스킬 vs. MCP 서버
에이전트를 확장하는 두 가지 주요 방법입니다. 스킬은 에이전트가 따르는 지침이 담긴 마크다운 파일입니다. 호출될 때까지 간략한 설명만 로드되어 컨텍스트 윈도우를 효율적으로 유지합니다. 스킬은 다음에 적합합니다.- 워크플로우와 규칙 (“배포 방법”, “코드 리뷰 체크리스트”)
- 참조 자료 (API 패턴, 스타일 가이드)
- 이름으로 트리거되는 재사용 가능한 프롬프트
- 외부 서비스 연결 (Notion, Linear, 데이터베이스)
- API 접근이 필요한 작업 (작업 생성, 데이터 쿼리)
- 지침이 아닌 실제 작업을 수행하는 도구
스킬은 에이전트가 어떻게 작동해야 하는지를 정의합니다. MCP 서버는 에이전트가 무엇에 접근할 수 있는지를 정의합니다. 둘 다 코딩 에이전트(Replit Agent 등)와 SDK로 빌드한 에이전트에서 작동합니다.
SDK vs. API 선택 기준
| 사용 사례 | 선택 |
|---|---|
| 다단계 작업 자동화 | Claude Agent SDK |
| 멀티 에이전트 워크플로우 | Claude Agent SDK |
| 간단한 채팅 앱 | Anthropic API |
| 단일 턴 작업 | Anthropic API |
Todoist 정리 에이전트 만들기
이 예제에서는 올바른 구조(에이전트, 도구, MCP 서버, 스킬, 권한 디렉터리가 이미 갖춰진)로 Claude Agent SDK 프로젝트를 스캐폴딩하는 Replit 템플릿을 사용합니다.1단계: 템플릿 리믹스
템플릿 열기
Replit에서 Claude Agent SDK 템플릿을 열고 Remix를 선택하여 자신만의 복사본을 만드세요.
2단계: Replit Integrations로 Todoist 연결
Agent에게 프롬프트를 보내기 전에, 에이전트가 상호작용해야 할 서비스를 먼저 연결하세요.- Replit 계정에서 replit.com/integrations로 이동합니다.
- Todoist를 찾아 계정을 연결합니다.
- Replit이 Todoist 데이터에 접근하도록 권한을 부여합니다.
Replit Integrations는 OAuth와 인증을 대신 처리합니다. 에이전트는 토큰을 직접 관리하지 않고도 Todoist API에 접근할 수 있습니다. 별도의 OAuth 플로우가 필요한 MCP 서버를 구성하는 것보다 훨씬 간단합니다.
3단계: Agent에게 에이전트 빌드 요청
최상의 결과를 위해 Replit Agent를 Plan Mode로 전환하세요. 빌드 전에 계획을 검토하므로 접근 방식을 확인할 기회가 생깁니다.이 프롬프트의 마지막 두 단락은 디버깅 후 추가되었습니다. 어떻게 인증할지(MCP OAuth가 아닌 Replit Integrations)와 최종 상태가 어떻게 보여야 하는지(받은 편지함 완전히 비우기)를 구체적으로 명시하면 반복 시간을 절약할 수 있습니다.
4단계: 계획 검토 및 빌드
Agent가 계획을 제시하면 다음 항목이 포함되어 있는지 확인하세요.- Todoist API용 커스텀 도구 (Todoist MCP 서버 아님)
- 작업, 레이블, 프로젝트를 가져오는 정리 에이전트
- 에이전트에 필요한 도구에 범위가 지정된 적절한 권한
- 워크플로우를 트리거하는 진입점
5단계: Anthropic API 키 추가
Claude Agent SDK는 Claude를 호출하기 위해 Anthropic API 키가 필요합니다.- Project Editor에서 Secrets 패널을 엽니다.
- API 키 값으로
ANTHROPIC_API_KEY라는 이름의 시크릿을 추가합니다.
Settings의 Replit vault에 Anthropic API 키를 저장해 두면, 모든 프로젝트에서 자동으로 사용할 수 있습니다.
6단계: 테스트 및 디버그
에이전트를 실행하고 Todoist 받은 편지함을 올바르게 처리하는지 확인하세요. 주의해야 할 일반적인 문제:- 받은 편지함이 비어 있지 않은데 “비어 있음”이라고 표시 — 받은 편지함 작업을 감지하는 API 응답 형식을 조정해야 할 수 있습니다. 에이전트가 다른 속성이 아닌 받은 편지함 프로젝트로 작업을 필터링하는지 확인하세요.
- 작업에 레이블이 추가되지만 프로젝트로 이동되지 않음 — 에이전트가 사용 가능한 프로젝트를 가져와 각 작업에 할당해야 한다고 프롬프트에 명시적으로 지정하세요.
- 인증 오류 — Replit Integrations에서 Todoist 통합이 연결되어 있고 에이전트 코드가 별도의 OAuth 플로우가 아닌 이를 사용하는지 확인하세요.
에이전트 배포
에이전트가 올바르게 작동하면 자동으로 실행되도록 배포하세요.
이벤트(웹훅, 수신 메시지)에 응답해야 하는 에이전트의 경우 대신 Reserved VM 배포를 사용하세요.
에이전트 확장
기본 기능이 작동하면 Replit에서 더 정교한 에이전트를 만들 수 있습니다.- 영구 메모리 추가 — Replit Database를 사용해 실행 간 상태 저장
- 파일 저장 — App Storage를 파일 기반 데이터에 사용
- 더 많은 서비스 연결 — 멀티 서비스 워크플로우를 위해 더 많은 Integrations 추가 (Slack, Linear, GitHub, Notion)
- 스킬 사용 — 에이전트에게 전문 지식과 지침을 제공하는 마크다운 스킬 파일 추가
다음 단계
- 전체 API 레퍼런스를 위한 Claude Agent SDK 문서 탐색
- Replit에서 챗봇과 이벤트 기반 워크플로우 빌드를 위한 에이전트 및 자동화 알아보기
- 배포 옵션에 대한 예약 배포 및 Reserved VM 배포 읽기
- 빌드 시작을 위한 Claude Agent SDK 템플릿 확인