Skip to main content
The Claude Agent 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.
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
  • How to publish your agent on a schedule with Scheduled Deployments

​
Prerequisites

​
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.
Multi-agent architectures keep each agent focused. Sub-agents get only the tools and context they need, which prevents context bloat and improves performance.

​
Core primitives

PrimitiveWhat it does
Query loopThe foundation: prompt, pick tools, execute, observe, repeat
AgentsSpecialized configurations with their own tools and instructions
ToolsActions agents can take—run commands, call APIs, edit files
MCP serversExternal processes that expose collections of tools (context-heavy, loaded upfront)
SkillsMarkdown instruction files that teach agents how to do things (context-efficient, loaded on demand)
PermissionsGranular 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
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.

​
When to use the SDK vs. the API

Use caseChoose
Automating multi-step tasksClaude Agent SDK
Multi-agent workflowsClaude Agent SDK
Simple chat appsAnthropic API
Single-turn tasksAnthropic 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

1

Open the template

Open the Claude Agent SDK template on Replit and select Remix to create your own copy.
2

Name your project

Give it a descriptive name (e.g., “My Todoist Agent”) and select Use Template.
3

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

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

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

​
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 your Replit Workspace.
  2. Add a secret named ANTHROPIC_API_KEY with your API key value.
If you’ve saved your Anthropic API key in your Replit Account Vault, it’s automatically available across all your projects.

​
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).
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.

​
Publish your agent

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

Open the Publish tab

In your Replit Workspace, select the Publish tab.
2

Choose Scheduled Deployment

Select Scheduled Deployment for time-based automation. Enter your desired schedule (e.g., “Every day at 5pm PST”).
3

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

Publish

Select Publish. Your agent is now live and runs on schedule.
For agents that need to respond to events (webhooks, incoming messages), use a Reserved VM Deployment instead.

​
Extend your agent

Once the basics work, you can build more sophisticated agents on Replit:
  • Add persistent memory — Use Replit Database to store state between runs
  • Store files — Use App Storage for file-based data
  • Connect more services — Add more 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