> ## 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와 Replit을 사용해 자율 AI 에이전트를 빌드하고 배포하는 방법을 단계별 Todoist 자동화 예제와 함께 알아봅니다.

export const AiPrompt = ({children}) => {
  return <CodeBlock className="relative block font-sans whitespace-pre-wrap break-words">
      <div className="pr-7">
        {children}
      </div>
    </CodeBlock>;
};

export const YouTubeEmbed = ({videoId, title = "YouTube video", startAt}) => {
  if (!videoId) {
    return null;
  }
  let url = "https://www.youtube.com/embed/" + videoId;
  if (startAt) {
    url = url + "?start=" + startAt;
  }
  return <Frame>
      <iframe src={url} title={title} allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowFullScreen></iframe>
    </Frame>;
};

[Claude Agent SDK](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/sdk)는 라이브러리로 제공되는 Claude Code입니다. Claude Code를 구동하는 에이전트와 동일한 에이전트를 프로그래밍 방식으로 생성한 다음, 코드로 실행할 수 있습니다. 반복적인 작업을 자동화된 워크플로우로 전환하고 Replit에 배포하세요.

<YouTubeEmbed videoId="jNpH_hOFvg4" title="Build and publish a Claude Agent SDK app on Replit" />

이 튜토리얼에서는 Todoist 받은 편지함을 정리하는 에이전트를 만듭니다. 작업을 가져오고, 레이블을 적용하고, 프로젝트별로 정렬한 다음, 일정에 따라 실행되도록 배포합니다.

## 배우게 될 내용

* Claude Agent SDK의 작동 방식과 사용 시점
* 핵심 구성 요소: 에이전트, 도구, MCP 서버, 스킬, 권한
* [Integrations](/references/integrations/overview)를 사용해 Replit에서 작업 자동화 에이전트 빌드하기
* [예약 배포](/references/publishing/scheduled-deployments)로 에이전트를 일정에 따라 배포하기

## 사전 요구 사항

* [Replit](https://replit.com) 계정 (배포용으로 Core 또는 Pro 플랜 권장)
* [Anthropic API 키](https://console.anthropic.com/)
* [Todoist](https://todoist.com) 계정 (또는 자동화하려는 다른 서비스)

## Claude Agent SDK 작동 방식

에이전트는 루프입니다. 프롬프트를 보내면 에이전트가 실행할 도구를 선택하고, 결과를 확인하고, 작업이 완료될 때까지 이 과정을 반복합니다.

프롬프트는 여러분이 제공합니다. 루프는 SDK가 처리합니다.

하지만 SDK는 한 걸음 더 나아갑니다. 오케스트레이터 에이전트가 각자의 도구와 컨텍스트 윈도우를 가진 전문 하위 에이전트에게 작업을 위임하는 **멀티 에이전트 아키텍처**를 구축할 수 있습니다.

<Tip>
  멀티 에이전트 아키텍처는 각 에이전트를 집중된 상태로 유지합니다. 하위 에이전트는 필요한 도구와 컨텍스트만 받으므로 컨텍스트 과부하를 방지하고 성능을 향상시킵니다.
</Tip>

### 핵심 구성 요소

| 구성 요소      | 역할                                                |
| ---------- | ------------------------------------------------- |
| **쿼리 루프**  | 기반: 프롬프트 → 도구 선택 → 실행 → 확인 → 반복                   |
| **에이전트**   | 자체 도구와 지침을 가진 전문화된 구성                             |
| **도구**     | 에이전트가 수행할 수 있는 작업 — 명령 실행, API 호출, 파일 편집          |
| **MCP 서버** | 도구 모음을 노출하는 외부 프로세스 (컨텍스트가 무거우며 처음에 로드됨)          |
| **스킬**     | 에이전트에게 작업 방법을 가르치는 마크다운 지침 파일 (컨텍스트 효율적, 필요 시 로드) |
| **권한**     | 각 에이전트가 접근하고 실행할 수 있는 항목에 대한 세밀한 제어               |

### 스킬 vs. MCP 서버

에이전트를 확장하는 두 가지 주요 방법입니다.

**스킬**은 에이전트가 따르는 지침이 담긴 마크다운 파일입니다. 호출될 때까지 간략한 설명만 로드되어 컨텍스트 윈도우를 효율적으로 유지합니다. 스킬은 다음에 적합합니다.

* 워크플로우와 규칙 ("배포 방법", "코드 리뷰 체크리스트")
* 참조 자료 (API 패턴, 스타일 가이드)
* 이름으로 트리거되는 재사용 가능한 프롬프트

**MCP 서버**는 도구를 노출하는 프로세스입니다. 모든 도구 설명이 처음에 로드되므로 컨텍스트가 무겁습니다. MCP 서버는 다음에 적합합니다.

* 외부 서비스 연결 (Notion, Linear, 데이터베이스)
* API 접근이 필요한 작업 (작업 생성, 데이터 쿼리)
* 지침이 아닌 실제 *작업을 수행하는* 도구

<Info>
  스킬은 에이전트가 *어떻게* 작동해야 하는지를 정의합니다. MCP 서버는 에이전트가 *무엇에* 접근할 수 있는지를 정의합니다. 둘 다 코딩 에이전트(Replit Agent 등)와 SDK로 빌드한 에이전트에서 작동합니다.
</Info>

### SDK vs. API 선택 기준

| 사용 사례         | 선택               |
| ------------- | ---------------- |
| 다단계 작업 자동화    | Claude Agent SDK |
| 멀티 에이전트 워크플로우 | Claude Agent SDK |
| 간단한 채팅 앱      | Anthropic API    |
| 단일 턴 작업       | Anthropic API    |

## Todoist 정리 에이전트 만들기

이 예제에서는 올바른 구조(에이전트, 도구, MCP 서버, 스킬, 권한 디렉터리가 이미 갖춰진)로 Claude Agent SDK 프로젝트를 스캐폴딩하는 Replit 템플릿을 사용합니다.

### 1단계: 템플릿 리믹스

<Steps>
  <Step title="템플릿 열기">
    Replit에서 [Claude Agent SDK 템플릿](https://replit.com/@matt/Claude-Agent-SDK)을 열고 **Remix**를 선택하여 자신만의 복사본을 만드세요.
  </Step>

  <Step title="프로젝트 이름 지정">
    설명적인 이름(예: "My Todoist Agent")을 지정하고 **Use Template**을 선택하세요.
  </Step>

  <Step title="프로젝트 구조 검토">
    환경이 로드되면 파일 사이드바를 엽니다. 전체 구조를 보려면 필요시 **Show Hidden Files**를 토글하세요.

    * `.agents/skills/` — Replit Agent에게 Claude Agent SDK 앱 빌드 방법을 가르치는 스킬
    * `src/agents/` — 에이전트 정의
    * `src/mcpServers/` — MCP 서버 구성
    * `src/permissions/` — 권한 정의
    * `src/skills/` — 에이전트용 스킬 (마크다운 파일)
    * `src/tools/` — 커스텀 도구 정의
  </Step>
</Steps>

<Tip>
  템플릿에는 Replit Agent에게 Claude Agent SDK 앱 빌드 방법을 가르치는 스킬이 포함되어 있습니다. 즉, Agent가 프롬프트를 받으면 이미 프레임워크를 이해하고 있습니다.
</Tip>

### 2단계: Replit Integrations로 Todoist 연결

Agent에게 프롬프트를 보내기 전에, 에이전트가 상호작용해야 할 서비스를 먼저 연결하세요.

1. Replit 계정에서 **replit.com/integrations**로 이동합니다.
2. **Todoist**를 찾아 계정을 연결합니다.
3. Replit이 Todoist 데이터에 접근하도록 권한을 부여합니다.

<Info>
  Replit Integrations는 OAuth와 인증을 대신 처리합니다. 에이전트는 토큰을 직접 관리하지 않고도 Todoist API에 접근할 수 있습니다. 별도의 OAuth 플로우가 필요한 MCP 서버를 구성하는 것보다 훨씬 간단합니다.
</Info>

### 3단계: Agent에게 에이전트 빌드 요청

최상의 결과를 위해 Replit Agent를 **Plan Mode**로 전환하세요. 빌드 전에 계획을 검토하므로 접근 방식을 확인할 기회가 생깁니다.

<AiPrompt>
  Claude Agent SDK 스킬을 사용하세요. Todoist 받은 편지함을 살펴보고 관련 레이블이나 보조 정보를 적용해 작업을 정리하는 에이전트를 만드세요.

  SDK를 사용해 에이전트가 Todoist와 상호작용할 수 있는 도구를 만들어야 합니다.

  결과는 트리거될 때 모든 작업과 사용 가능한 프로젝트를 로드하고, 작업을 다듬은 다음 적절히 정리하는 에이전트여야 합니다.

  모든 인증에는 Replit Todoist 통합을 사용하세요. MCP 서버는 이 맥락에서 작동하지 않는 OAuth가 필요하므로, Todoist MCP 서버 대신 Todoist REST API와 커스텀 도구를 사용하세요.

  에이전트는 프로젝트 목록을 가져와 받은 편지함의 각 항목에 관련 프로젝트를 할당하여 받은 편지함을 완전히 비워야 합니다.
</AiPrompt>

<Note>
  이 프롬프트의 마지막 두 단락은 디버깅 후 추가되었습니다. *어떻게* 인증할지(MCP OAuth가 아닌 Replit Integrations)와 최종 상태가 *어떻게* 보여야 하는지(받은 편지함 완전히 비우기)를 구체적으로 명시하면 반복 시간을 절약할 수 있습니다.
</Note>

### 4단계: 계획 검토 및 빌드

Agent가 계획을 제시하면 다음 항목이 포함되어 있는지 확인하세요.

1. Todoist API용 **커스텀 도구** (Todoist MCP 서버 아님)
2. 작업, 레이블, 프로젝트를 가져오는 **정리 에이전트**
3. 에이전트에 필요한 도구에 범위가 지정된 **적절한 권한**
4. 워크플로우를 트리거하는 **진입점**

만족스러우면 계획을 승인하고, Agent를 **high autonomy**로 설정하고 빌드를 진행하세요.

### 5단계: Anthropic API 키 추가

Claude Agent SDK는 Claude를 호출하기 위해 Anthropic API 키가 필요합니다.

1. Project Editor에서 **Secrets** 패널을 엽니다.
2. API 키 값으로 `ANTHROPIC_API_KEY`라는 이름의 시크릿을 추가합니다.

<Info>
  [Settings의 Replit vault](https://replit.com/settings)에 Anthropic API 키를 저장해 두면, 모든 프로젝트에서 자동으로 사용할 수 있습니다.
</Info>

### 6단계: 테스트 및 디버그

에이전트를 실행하고 Todoist 받은 편지함을 올바르게 처리하는지 확인하세요. 주의해야 할 일반적인 문제:

* **받은 편지함이 비어 있지 않은데 "비어 있음"이라고 표시** — 받은 편지함 작업을 감지하는 API 응답 형식을 조정해야 할 수 있습니다. 에이전트가 다른 속성이 아닌 받은 편지함 프로젝트로 작업을 필터링하는지 확인하세요.
* **작업에 레이블이 추가되지만 프로젝트로 이동되지 않음** — 에이전트가 사용 가능한 프로젝트를 가져와 각 작업에 할당해야 한다고 프롬프트에 명시적으로 지정하세요.
* **인증 오류** — Replit Integrations에서 Todoist 통합이 연결되어 있고 에이전트 코드가 별도의 OAuth 플로우가 아닌 이를 사용하는지 확인하세요.

<Tip>
  디버깅은 AI로 빌드하는 과정의 일부입니다. 무언가 작동하지 않을 때는 출력을 살펴보고, 에이전트가 예상과 다르게 *무엇을* 했는지 파악하고, 더 구체적인 프롬프트를 제공하세요. 각 수정을 통해 다음에 처음부터 포함해야 할 내용을 알게 됩니다.
</Tip>

## 에이전트 배포

에이전트가 올바르게 작동하면 자동으로 실행되도록 배포하세요.

<Steps>
  <Step title="Publish 탭 열기">
    Project Editor에서 **Publish** 탭을 선택합니다.
  </Step>

  <Step title="예약 배포 선택">
    시간 기반 자동화를 위해 **Scheduled Deployment**를 선택합니다. 원하는 일정을 입력하세요 (예: "매일 오후 5시 PST").
  </Step>

  <Step title="구성 확인">
    실행 명령이 기본 진입점 파일을 가리키는지, `ANTHROPIC_API_KEY` 시크릿이 배포 시크릿에 포함되어 있는지 확인하세요.
  </Step>

  <Step title="배포">
    **Publish**를 선택합니다. 이제 에이전트가 라이브 상태이며 일정에 따라 실행됩니다.
  </Step>
</Steps>

이벤트(웹훅, 수신 메시지)에 응답해야 하는 에이전트의 경우 대신 [Reserved VM 배포](/references/publishing/reserved-vm-deployments)를 사용하세요.

## 에이전트 확장

기본 기능이 작동하면 Replit에서 더 정교한 에이전트를 만들 수 있습니다.

* **영구 메모리 추가** — [Replit Database](/references/data-and-storage/sql-database)를 사용해 실행 간 상태 저장
* **파일 저장** — [App Storage](/references/data-and-storage/object-storage)를 파일 기반 데이터에 사용
* **더 많은 서비스 연결** — 멀티 서비스 워크플로우를 위해 더 많은 [Integrations](/references/integrations/overview) 추가 (Slack, Linear, GitHub, Notion)
* **스킬 사용** — 에이전트에게 전문 지식과 지침을 제공하는 마크다운 스킬 파일 추가

## 다음 단계

* 전체 API 레퍼런스를 위한 [Claude Agent SDK 문서](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/sdk) 탐색
* Replit에서 챗봇과 이벤트 기반 워크플로우 빌드를 위한 [에이전트 및 자동화](/references/agent/automations) 알아보기
* 배포 옵션에 대한 [예약 배포](/references/publishing/scheduled-deployments) 및 [Reserved VM 배포](/references/publishing/reserved-vm-deployments) 읽기
* 빌드 시작을 위한 [Claude Agent SDK 템플릿](https://replit.com/@matt/Claude-Agent-SDK) 확인