> ## 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サーバー、スキル、パーミッション
* Replitの[Integrations](/references/integrations/overview)を使ったタスク自動化エージェントの構築方法
* [Scheduled Deployments](/references/publishing/scheduled-deployments)を使ったスケジュール実行への公開方法

## 前提条件

* [Replit](https://replit.com)アカウント（Deploymentsにはコアまたはプロプランを推奨）
* [Anthropic APIキー](https://console.anthropic.com/)
* [Todoist](https://todoist.com)アカウント（または自動化したい他のサービス）

## Claude Agent SDKの仕組み

エージェントはループで動作します。プロンプトを送ると、エージェントは実行するツールを選び、結果を観察し、タスクが完了するまで繰り返します。

プロンプトを提供するのはあなたです。ループの処理はSDKが行います。

さらにSDKは、オーケストレーターエージェントが専門化されたサブエージェントにタスクを委任する**マルチエージェントアーキテクチャ**の構築もサポートします。各サブエージェントは独自のツールとコンテキストウィンドウを持ちます。

<Tip>
  マルチエージェントアーキテクチャにより、各エージェントの役割を絞り込めます。サブエージェントには必要なツールとコンテキストだけが渡されるため、コンテキストの肥大化を防ぎ、パフォーマンスが向上します。
</Tip>

### 主要なプリミティブ

| プリミティブ      | 説明                                                    |
| ----------- | ----------------------------------------------------- |
| **クエリループ**  | 基本動作: プロンプト→ツール選択→実行→観察→繰り返し                          |
| **エージェント**  | 独自のツールと指示を持つ専門化された設定                                  |
| **ツール**     | エージェントが実行できるアクション（コマンド実行、API呼び出し、ファイル編集など）            |
| **MCPサーバー** | ツールのコレクションを公開する外部プロセス（コンテキスト負荷が高く、起動時に読み込まれる）         |
| **スキル**     | エージェントに作業方法を教えるMarkdown指示ファイル（コンテキスト効率が高く、必要時に読み込まれる） |
| **パーミッション** | 各エージェントがアクセス・実行できる内容を細かく制御する設定                        |

### スキルとMCPサーバーの違い

エージェントを拡張する主な方法は2つあります:

**スキル**はエージェントが従う指示が書かれたMarkdownファイルです。呼び出されるまでは簡単な説明のみが読み込まれるため、コンテキストウィンドウをスリムに保てます。スキルの用途:

* ワークフローや規約（「デプロイ方法」「コードレビューチェックリスト」など）
* 参照資料（APIパターン、スタイルガイド）
* 名前で呼び出す再利用可能なプロンプト

**MCPサーバー**はツールを公開するプロセスです。すべてのツールの説明が起動時に読み込まれるため、コンテキスト負荷が高くなります。MCPサーバーの用途:

* 外部サービスへの接続（Notion、Linear、データベースなど）
* APIアクセスが必要なアクション（タスクの作成、データのクエリなど）
* 指示を与えるだけでなく、\_実際に何かを行う\_ツール

<Info>
  スキルはエージェントが*どのように*動くべきかを定義します。MCPサーバーはエージェントが*何に*アクセスできるかを定義します。どちらもコーディングエージェント（Replit Agentなど）およびSDKで作成するエージェントで使用できます。
</Info>

### SDKとAPIの使い分け

| ユースケース          | 選択               |
| --------------- | ---------------- |
| 複数ステップのタスクの自動化  | Claude Agent SDK |
| マルチエージェントワークフロー | Claude Agent SDK |
| シンプルなチャットアプリ    | Anthropic API    |
| 単発のタスク          | Anthropic API    |

## Todoist整理エージェントを作成する

このウォークスルーでは、Claude Agent SDKプロジェクトに適切な構造（エージェント、ツール、MCPサーバー、スキル、パーミッションのディレクトリがすでに用意されている）をスキャフォールドする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/` — エージェント用スキル（Markdownファイル）
    * `src/tools/` — カスタムツールの定義
  </Step>
</Steps>

<Tip>
  テンプレートには、Replit AgentにClaude Agent SDKアプリの作成方法を教えるスキルが含まれています。そのため、Agentにプロンプトを入力する際、AgentはすでにこのフレームワークをAについて把握しています。
</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>
  Use the Claude Agent SDK skill. Build an agent that looks at my Todoist inbox and organizes my tasks by applying relevant labels or supporting information.

  You should create tools that allow the agent to interact with Todoist using the SDK.

  The result should be an agent that, when triggered, loads all tasks and available projects, polishes them, then organizes them appropriately.

  Be sure to use the Replit Todoist integration for all authentication. Use custom tools with the Todoist REST API rather than the Todoist MCP server, since the MCP server requires OAuth which doesn't work in this context.

  The agent should also fetch a list of projects and assign a relevant project to each item in my inbox, clearing the inbox completely.
</AiPrompt>

<Note>
  このプロンプトの最後の2段落は、デバッグ後に追加されました。認証方法（ReplitのIntegrations、MCPのOAuthではない）と最終的な状態（受信トレイを完全に空にする）を具体的に指定することで、試行錯誤の時間を節約できます。
</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. `ANTHROPIC_API_KEY`という名前のシークレットに、APIキーの値を追加します。

<Info>
  [ReplitのSettingsにあるvault](https://replit.com/settings)にAnthropicのAPIキーを保存している場合、すべてのプロジェクトで自動的に使用できます。
</Info>

### ステップ6: テストとデバッグ

エージェントを実行し、Todoistの受信トレイが正しく処理されることを確認します。よくある問題として注意すべき点:

* **受信トレイが空でないのに「Inbox is empty」と表示される** — 受信トレイのタスクを検出するAPIレスポンス形式の調整が必要な場合があります。エージェントが受信トレイのプロジェクトでタスクをフィルタリングしているか（別のプロパティではなく）を確認してください。
* **タスクにラベルは付くがプロジェクトに移動しない** — エージェントが利用可能なプロジェクトを取得し、各タスクにプロジェクトを割り当てるよう、プロンプトに明示的に指定してください。
* **認証エラー** — Replit IntegrationsでTodoistの接続が完了しているか、エージェントのコードがそれを使用しているか（独自のOAuthフローではなく）を確認してください。

<Tip>
  デバッグはAIを使った開発の一部です。うまくいかない場合は、出力を確認し、エージェントが期待と\_どこで\_異なる動作をしたかを特定し、より具体的なプロンプトを入力してください。修正のたびに、次回最初から含めるべき内容が分かってきます。
</Tip>

## エージェントを公開する

エージェントが正しく動作したら、自動実行できるように公開します。

<Steps>
  <Step title="Publishタブを開く">
    Project Editorで**Publish**タブを選択します。
  </Step>

  <Step title="Scheduled Deploymentを選ぶ">
    時間ベースの自動化には**Scheduled Deployment**を選択します。希望するスケジュール（例: "Every day at 5pm PST"）を入力します。
  </Step>

  <Step title="設定を確認する">
    実行コマンドがメインエントリポイントファイルを指していること、および`ANTHROPIC_API_KEY`シークレットがデプロイのシークレットに含まれていることを確認します。
  </Step>

  <Step title="公開する">
    **Publish**を選択します。エージェントが公開され、スケジュールに従って実行されます。
  </Step>
</Steps>

イベント（Webhook、受信メッセージ）に応答する必要があるエージェントには、代わりに[Reserved VM Deployment](/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など）を追加してマルチサービスのワークフローを構築する
* **スキルを使う** — Markdownのスキルファイルを追加してエージェントに専門知識と指示を与える

## 次のステップ

* [Claude Agent SDKドキュメント](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/sdk)でAPIリファレンスの全体を確認する
* [Agents & Automations](/references/agent/automations)でReplitにおけるチャットボットとイベント駆動型ワークフローの構築方法を学ぶ
* デプロイのオプションについては[Scheduled Deployments](/references/publishing/scheduled-deployments)と[Reserved VM Deployments](/references/publishing/reserved-vm-deployments)を参照する
* [Claude Agent SDKテンプレート](https://replit.com/@matt/Claude-Agent-SDK)から構築を始める