Getting Started with a Todo-Tracking Agent

Imagine having an AI assistant that handles your daily tasks seamlessly—just chat with it in plain English to add, list, complete, or delete todos. That's exactly what you'll build using Claude's Agent SDK. This example demonstrates the core capabilities of the SDK by creating a conversational agent that persists todo items in memory and responds intelligently to user instructions. It's a perfect entry point for developers looking to harness agentic AI for practical applications like personal productivity tools.

The full source code for this project is available in the Anthropic SDK TypeScript repository. You can clone it directly to experiment and extend it.

Prerequisites for Development

Before diving in, ensure your environment is set up correctly:

• Node.js version 20 or higher: The Agent SDK relies on modern JavaScript features and async patterns.
• npm (Node Package Manager): Comes bundled with Node.js; use it to manage dependencies.
• Anthropic API Key: Sign up at the Anthropic Console, generate a key, and store it securely as an environment variable named ANTHROPIC_API_KEY.

These requirements keep the setup lightweight while ensuring compatibility with Claude's latest models.

Step-by-Step Installation

1. Clone the Repository: Open your terminal and run:

git clone https://github.com/anthropics/anthropic-sdk-typescript.git cd anthropic-sdk-typescript/examples/agent-sdk/todo-tracking

This positions you in the todo-tracking example directory.

2. **Install Dependencies**:
Execute:
```bash
npm install

This pulls in the @anthropic-ai/sdk and other essentials like dotenv for environment management.

1. Configure Environment: Create a .env file in the project root:

ANTHROPIC_API_KEY=your_api_key_here

Replace `your_api_key_here` with your actual key. Never commit this file to version control—add `.env` to `.gitignore` if not already present.

With these steps complete, you're ready to launch the agent.

## Launching and Interacting with the Agent

Run the development server:
```bash
npm run dev

This starts an interactive console session. You'll see a prompt like You are TodoBot >. Type your commands naturally:

• Add a task: "Add 'Buy groceries' to my todo list."
• List tasks: "Show me all my todos."
• Complete a task: "Mark 'Buy groceries' as done."
• Delete a task: "Remove 'Buy groceries'."

The agent processes your input, calls appropriate tools if needed, and responds. Sessions continue until you type 'exit' or 'quit'. Here's a sample interaction:

You are TodoBot > Add 'Finish report' due tomorrow
Added 'Finish report' to your todos!

You are TodoBot > List todos
Here are your current todos:
1. Finish report (due tomorrow)

You are TodoBot > Complete the first todo
'Finish report (due tomorrow)' has been marked as complete!

This loop showcases the agent's conversational flow, making task management feel intuitive and human-like.

Deep Dive: Architecture and Mechanics

At its heart, the agent uses the Agent class from @anthropic-ai/sdk. Here's how it all comes together:

Defining Tools

Tools are the agent's superpowers—functions it can invoke based on user intent. Four tools power this todo app:

• addTodo: Creates a new todo with text and optional dueDate.
• listTodos: Returns all todos as a formatted string, including completed ones.
• completeTodo: Marks a todo as done by exact text match.
• deleteTodo: Removes a todo by text.

Each tool is defined with a name, description, and inputSchema using JSON Schema for type safety:

import { z } from 'zod';

const addTodoSchema = z.object({
  text: z.string().describe('The text of the todo'),
  dueDate: z.string().optional().describe('Optional due date'),
});

export type AddTodoInput = z.infer<typeof addTodoSchema>;

Tools are registered in an array passed to the Agent constructor.

In-Memory Todo Storage

Todos live in a simple array:

let todos: Todo[] = [];

interface Todo {
  id: string;
  text: string;
  completed: boolean;
  dueDate?: string;
}

Tool functions mutate this array directly. For production, you'd swap this for a database like SQLite or PostgreSQL.

The Agent Loop

The magic happens in the main script:

1. Initialize agent with Claude model (e.g., claude-3-5-sonnet-20240620), system prompt, and tools.
2. Enter a while loop:
   • Read user input.
   • Call agent.io() with input.
   • Process tool calls: Execute each, feed results back.
   • Display final assistant message.
3. Repeat until user exits.

The system prompt sets the agent's persona:

You are TodoBot, a helpful assistant that helps users manage their todo list...

It instructs when to use tools and how to respond conversationally.

Customization: Tailor the Agent to Your Needs

The SDK's flexibility shines in customization:

Modify the System Prompt

Tweak behavior:

const agent = new Agent({
  name: 'TodoBot',
  system: 'You are a strict taskmaster...',
  // ...
});

Add rules like prioritizing urgent tasks or integrating weather checks.

Extend with More Tools

Want reminders? Add a sendReminder tool:

const sendReminderSchema = z.object({
  todoId: z.string().describe('ID of todo to remind about'),
});

Implement it to log or email notifications.

Persist State Across Sessions

In-memory storage resets on restart. For durability:

• File-based: Use fs to read/write todos.json.

import fs from 'fs/promises';

const saveTodos = async () => { await fs.writeFile('todos.json', JSON.stringify(todos, null, 2)); };

// Call after mutations

- **Database**: Integrate Prisma or Drizzle ORM for scalable apps.

- **Session Management**: Use unique session IDs for multi-user support.

### Model Selection and Streaming

Switch models via `model` param (e.g., `claude-3-opus-20240229` for complex reasoning). Enable streaming for real-time responses:
```typescript
agent.io('List todos', { stream: true });

Real-World Applications and Extensions

This todo agent is a foundation for more:

• Personal Kanban: Add priority levels and categories.
• Team Task Manager: Integrate Slack/Discord bots via webhooks.
• Integration with Calendars: Tools for Google Calendar sync.

In enterprise settings, combine with MCP (Managed Compute Platform) for scalable deployments.

Troubleshooting Common Issues

• API Key Errors: Verify ANTHROPIC_API_KEY in .env and reload terminal.
• Tool Execution Fails: Check schema matches input types.
• Rate Limits: Monitor usage in Anthropic Console; upgrade plan if needed.

Next Steps

Fork the GitHub repo, build on it, and explore other Agent SDK examples like code interpreters or web search agents. Deploy to Vercel or Replit for sharing.

This project illustrates agentic workflows: tools + reasoning + conversation = powerful AI assistants. Start coding today!