> ## 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.

# Build and publish a Claude Agent SDK app

> Learn how to build and publish autonomous AI agents using the Claude Agent SDK and Replit, with a step-by-step Todoist automation example.

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 WistiaEmbed = ({videoId, title = "Wistia video", playerColor = "FF0000", controlsVisibleOnLoad = false}) => {
  if (!videoId) {
    return null;
  }
  const url = "https://fast.wistia.net/embed/iframe/" + videoId + "?seo=false&playerColor=" + playerColor + "&controlsVisibleOnLoad=" + controlsVisibleOnLoad;
  return <Frame>
      <iframe src={url} title={title} allow="autoplay; fullscreen" allowFullScreen></iframe>
    </Frame>;
};

The [Claude Agent SDK](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/sdk) is Claude Code as a library. It lets you programmatically create the same agents that power Claude Code, then execute them as code. Turn repetitive tasks into automated workflows and publish them on Replit.

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

In this tutorial, you build an agent that organizes a Todoist inbox—fetching tasks, applying labels, and sorting them into projects—then publish it to run on a schedule.

## What you'll learn

* How the Claude Agent SDK works and when to use it
* Core primitives: agents, tools, MCP servers, skills, and permissions
* How to build a task automation agent on Replit using [Integrations](/replitai/integrations)
* How to publish your agent on a schedule with [Scheduled Deployments](/cloud-services/deployments/scheduled-deployments)

## Prerequisites

* A [Replit](https://replit.com) account (Core or Pro plan recommended for Deployments)
* An [Anthropic API key](https://console.anthropic.com/)
* A [Todoist](https://todoist.com) account (or another service you want to automate)

## How the Claude Agent SDK works

An agent is a loop: you send a prompt, the agent picks tools to execute, observes the results, and repeats until the task is complete.

You provide the prompt. The SDK handles the loop.

But the SDK goes further. It lets you build **multi-agent architectures** where an orchestrator agent delegates tasks to specialized sub-agents, each with their own tools and context windows.

<Tip>
  Multi-agent architectures keep each agent focused. Sub-agents get only the tools and context they need, which prevents context bloat and improves performance.
</Tip>

### Core primitives

| Primitive       | What it does                                                                                        |
| --------------- | --------------------------------------------------------------------------------------------------- |
| **Query loop**  | The foundation: prompt, pick tools, execute, observe, repeat                                        |
| **Agents**      | Specialized configurations with their own tools and instructions                                    |
| **Tools**       | Actions agents can take—run commands, call APIs, edit files                                         |
| **MCP servers** | External processes that expose collections of tools (context-heavy, loaded upfront)                 |
| **Skills**      | Markdown instruction files that teach agents how to do things (context-efficient, loaded on demand) |
| **Permissions** | Granular controls over what each agent can access and execute                                       |

### Skills vs. MCP servers

These are the two main ways to extend your agents:

**Skills** are markdown files with instructions your agent follows. Only a brief description loads until invoked, keeping the context window lean. Use skills for:

* Workflows and conventions ("how to deploy," "code review checklist")
* Reference materials (API patterns, style guides)
* Reusable prompts triggered by name

**MCP servers** are processes that expose tools. All tool descriptions load upfront, making them context-heavy. Use MCP servers for:

* Connecting to external services (Notion, Linear, databases)
* Actions that need API access (create tasks, query data)
* Tools that *do* things, not just instruct

<Info>
  Skills define *how* your agent should work. MCP servers define *what* your agent can access. Both work for coding agents (like Replit Agent) and agents you build with the SDK.
</Info>

### When to use the SDK vs. the API

| Use case                    | Choose           |
| --------------------------- | ---------------- |
| Automating multi-step tasks | Claude Agent SDK |
| Multi-agent workflows       | Claude Agent SDK |
| Simple chat apps            | Anthropic API    |
| Single-turn tasks           | Anthropic API    |

## Build a Todoist organizer agent

This walkthrough uses a Replit template that scaffolds a Claude Agent SDK project with the right structure—agents, tools, MCP servers, skills, and permissions directories already in place.

### Step 1: Remix the template

<Steps>
  <Step title="Open the template">
    Open the [Claude Agent SDK template](https://replit.com/@matt/Claude-Agent-SDK) on Replit and select **Remix** to create your own copy.
  </Step>

  <Step title="Name your project">
    Give it a descriptive name (e.g., "My Todoist Agent") and select **Use Template**.
  </Step>

  <Step title="Review the project structure">
    Once the environment loads, open the file sidebar. Toggle **Show Hidden Files** if needed to see the full structure:

    * `.agents/skills/` — Skills that teach Replit Agent how to build Claude Agent SDK apps
    * `src/agents/` — Agent definitions
    * `src/mcpServers/` — MCP server configurations
    * `src/permissions/` — Permission definitions
    * `src/skills/` — Skills for your agents (markdown files)
    * `src/tools/` — Custom tool definitions
  </Step>
</Steps>

<Tip>
  The template includes a skill that teaches Replit Agent how to build Claude Agent SDK apps. This means Agent already understands the framework when you prompt it.
</Tip>

### Step 2: Connect Todoist via Replit Integrations

Before prompting Agent, connect the service your agent needs to interact with.

1. Go to **replit.com/integrations** in your Replit account.
2. Find **Todoist** and connect your account.
3. Authorize Replit to access your Todoist data.

<Info>
  Replit Integrations handle OAuth and authentication for you. Your agent can access the Todoist API without managing tokens directly. This is simpler than configuring a separate MCP server that requires its own OAuth flow.
</Info>

### Step 3: Prompt Agent to build your agent

Switch Replit Agent into **Plan Mode** for best results—it reviews the plan before building, giving you a chance to verify the approach.

<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>
  The final two paragraphs of this prompt were added after debugging. Being specific about *how* to authenticate (Replit Integrations, not MCP OAuth) and *what* the end state should look like (inbox completely cleared) saves iteration time.
</Note>

### Step 4: Review the plan and build

When Agent presents its plan, verify it includes:

1. **Custom tools** for the Todoist API (not the Todoist MCP server)
2. **An organizer agent** that fetches tasks, labels, and projects
3. **Proper permissions** scoped to the tools your agent needs
4. **An entry point** that triggers the workflow

Once satisfied, approve the plan, set Agent to **high autonomy**, and let it build.

### Step 5: Add your Anthropic API key

The Claude Agent SDK requires an Anthropic API key to call Claude.

1. Open the **Secrets** pane in the Project Editor.
2. Add a secret named `ANTHROPIC_API_KEY` with your API key value.

<Info>
  If you've saved your Anthropic API key in your [Replit vault in Settings](https://replit.com/settings), it's automatically available across all your projects.
</Info>

### Step 6: Test and debug

Run the agent and verify it processes your Todoist inbox correctly. Common issues to watch for:

* **"Inbox is empty" when it's not** — The API response format for detecting inbox tasks may need adjustment. Check that the agent filters tasks by the inbox project, not a different property.
* **Tasks get labels but don't move to projects** — Be explicit in your prompt that the agent should fetch available projects and assign each task to one.
* **Authentication errors** — Verify the Todoist integration is connected in Replit Integrations and that your agent code uses it (not a separate OAuth flow).

<Tip>
  Debugging is part of building with AI. When something doesn't work, look at the output, identify *what* the agent did differently than expected, and provide a more specific prompt. Each correction teaches you what to include upfront next time.
</Tip>

## Publish your agent

Once your agent works correctly, publish it to run automatically.

<Steps>
  <Step title="Open the Publish tab">
    In the Project Editor, select the **Publish** tab.
  </Step>

  <Step title="Choose Scheduled Deployment">
    Select **Scheduled Deployment** for time-based automation. Enter your desired schedule (e.g., "Every day at 5pm PST").
  </Step>

  <Step title="Verify configuration">
    Confirm the run command points to your main entry point file and that your `ANTHROPIC_API_KEY` secret is included in the deployment secrets.
  </Step>

  <Step title="Publish">
    Select **Publish**. Your agent is now live and runs on schedule.
  </Step>
</Steps>

For agents that need to respond to events (webhooks, incoming messages), use a [Reserved VM Deployment](/cloud-services/deployments/reserved-vm-deployments) instead.

## Extend your agent

Once the basics work, you can build more sophisticated agents on Replit:

* **Add persistent memory** — Use [Replit Database](/cloud-services/storage-and-databases/sql-database) to store state between runs
* **Store files** — Use [App Storage](/cloud-services/storage-and-databases/object-storage) for file-based data
* **Connect more services** — Add more [Integrations](/replitai/integrations) (Slack, Linear, GitHub, Notion) for multi-service workflows
* **Use skills** — Add markdown skill files to give your agents specialized knowledge and instructions

## Next steps

* Explore the [Claude Agent SDK documentation](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/sdk) for the full API reference
* Learn about [Agents & Automations](/core-concepts/agent/agents-and-automations) for building chatbots and event-driven workflows on Replit
* Read about [Scheduled Deployments](/cloud-services/deployments/scheduled-deployments) and [Reserved VM Deployments](/cloud-services/deployments/reserved-vm-deployments) for deployment options
* Check out the [Claude Agent SDK template](https://replit.com/@matt/Claude-Agent-SDK) to start building