배우게 될 내용
- Claude Agent SDK의 작동 방식과 사용 시점
- 핵심 구성 요소: 에이전트, 도구, MCP 서버, 스킬, 권한
- Integrations를 사용해 Replit에서 작업 자동화 에이전트 빌드하기
- 예약 배포로 에이전트를 일정에 따라 배포하기
사전 요구 사항
- Replit 계정 (배포용으로 Core 또는 Pro 플랜 권장)
- Anthropic API 키
- Todoist 계정 (또는 자동화하려는 다른 서비스)
Claude Agent SDK 작동 방식
에이전트는 루프입니다. 프롬프트를 보내면 에이전트가 실행할 도구를 선택하고, 결과를 확인하고, 작업이 완료될 때까지 이 과정을 반복합니다. 프롬프트는 여러분이 제공합니다. 루프는 SDK가 처리합니다. 하지만 SDK는 한 걸음 더 나아갑니다. 오케스트레이터 에이전트가 각자의 도구와 컨텍스트 윈도우를 가진 전문 하위 에이전트에게 작업을 위임하는 멀티 에이전트 아키텍처를 구축할 수 있습니다.핵심 구성 요소
스킬 vs. MCP 서버
에이전트를 확장하는 두 가지 주요 방법입니다. 스킬은 에이전트가 따르는 지침이 담긴 마크다운 파일입니다. 호출될 때까지 간략한 설명만 로드되어 컨텍스트 윈도우를 효율적으로 유지합니다. 스킬은 다음에 적합합니다.- 워크플로우와 규칙 (“배포 방법”, “코드 리뷰 체크리스트”)
- 참조 자료 (API 패턴, 스타일 가이드)
- 이름으로 트리거되는 재사용 가능한 프롬프트
- 외부 서비스 연결 (Notion, Linear, 데이터베이스)
- API 접근이 필요한 작업 (작업 생성, 데이터 쿼리)
- 지침이 아닌 실제 작업을 수행하는 도구
스킬은 에이전트가 어떻게 작동해야 하는지를 정의합니다. MCP 서버는 에이전트가 무엇에 접근할 수 있는지를 정의합니다. 둘 다 코딩 에이전트(Replit Agent 등)와 SDK로 빌드한 에이전트에서 작동합니다.
SDK vs. API 선택 기준
Todoist 정리 에이전트 만들기
이 예제에서는 올바른 구조(에이전트, 도구, MCP 서버, 스킬, 권한 디렉터리가 이미 갖춰진)로 Claude Agent SDK 프로젝트를 스캐폴딩하는 Replit 템플릿을 사용합니다.1단계: 템플릿 리믹스
1
템플릿 열기
Replit에서 Claude Agent SDK 템플릿을 열고 Remix를 선택하여 자신만의 복사본을 만드세요.
2
프로젝트 이름 지정
설명적인 이름(예: “My Todoist Agent”)을 지정하고 Use Template을 선택하세요.
3
프로젝트 구조 검토
환경이 로드되면 파일 사이드바를 엽니다. 전체 구조를 보려면 필요시 Show Hidden Files를 토글하세요.
.agents/skills/— Replit Agent에게 Claude Agent SDK 앱 빌드 방법을 가르치는 스킬src/agents/— 에이전트 정의src/mcpServers/— MCP 서버 구성src/permissions/— 권한 정의src/skills/— 에이전트용 스킬 (마크다운 파일)src/tools/— 커스텀 도구 정의
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 플로우가 아닌 이를 사용하는지 확인하세요.
에이전트 배포
에이전트가 올바르게 작동하면 자동으로 실행되도록 배포하세요.1
Publish 탭 열기
Project Editor에서 Publish 탭을 선택합니다.
2
예약 배포 선택
시간 기반 자동화를 위해 Scheduled Deployment를 선택합니다. 원하는 일정을 입력하세요 (예: “매일 오후 5시 PST”).
3
구성 확인
실행 명령이 기본 진입점 파일을 가리키는지,
ANTHROPIC_API_KEY 시크릿이 배포 시크릿에 포함되어 있는지 확인하세요.4
배포
Publish를 선택합니다. 이제 에이전트가 라이브 상태이며 일정에 따라 실행됩니다.
에이전트 확장
기본 기능이 작동하면 Replit에서 더 정교한 에이전트를 만들 수 있습니다.- 영구 메모리 추가 — Replit Database를 사용해 실행 간 상태 저장
- 파일 저장 — App Storage를 파일 기반 데이터에 사용
- 더 많은 서비스 연결 — 멀티 서비스 워크플로우를 위해 더 많은 Integrations 추가 (Slack, Linear, GitHub, Notion)
- 스킬 사용 — 에이전트에게 전문 지식과 지침을 제공하는 마크다운 스킬 파일 추가
다음 단계
- 전체 API 레퍼런스를 위한 Claude Agent SDK 문서 탐색
- Replit에서 챗봇과 이벤트 기반 워크플로우 빌드를 위한 에이전트 및 자동화 알아보기
- 배포 옵션에 대한 예약 배포 및 Reserved VM 배포 읽기
- 빌드 시작을 위한 Claude Agent SDK 템플릿 확인