AI Agents Examples

中文版 | English

Educational project demonstrating how to build various types of AI Agents using Python and Anthropic SDK.

⚠️ Attribution

This project is based on the excellent tutorial at learn-claude-agents.vercel.app.

The majority of the code and concepts come from that tutorial. This repository serves as a complement by providing complete, runnable implementations of the examples presented there.

Huge thanks to the original tutorial authors for creating such an amazing learning resource!

Overview

This project contains working examples of AI Agent patterns, progressing from basic concepts to advanced techniques:

Foundation

• s01_agent_loop.py - Basic agent loop with tool calling
• s02_tool_use.py - Safe file operations with security boundaries
• s03_todo_write.py - Todo manager with Nag Reminder pattern

Advanced Patterns

• s04_subagent.py - Parent agent spawning subagents for focused tasks
• s05_skill_loading.py - Dynamic skill loading from markdown files
• s06_context_compact.py - Three-layer context compaction strategy

Systems

• s07_task_system.py - Persistent task graph with dependency tracking
• s08_background_tasks.py - Background daemon threads for parallel work
• s09_agent_teams.py - Multi-agent teams with file-based mailboxes
• s10_team_protocols.py - Team protocols for shutdown and plan approval

Features

• Anthropic SDK: Using Claude models for agent implementation
• Security: Path traversal protection and workspace isolation
• Advanced Patterns: Subagents, skill loading, context compaction
• Multi-Agent: Teams, mailboxes, protocols, background tasks
• Educational: Clean, well-commented code for learning

Setup

1. Clone the repository:

git clone <your-repo-url>
cd learn-claude-agents

2. Install dependencies using uv:

uv sync

3. Configure environment variables:

cp env.example .env

Edit .env with your API credentials:

ANTHROPIC_AUTH_TOKEN=your-anthropic-key-here
ANTHROPIC_BASE_URL=https://api.anthropic.com
ANTHROPIC_MODEL_ID=claude-sonnet-4-5

Usage

Run any example:

uv run agents/s01_agent_loop.py
uv run agents/s02_tool_use.py
uv run agents/s03_todo_write.py
uv run agents/s04_subagent.py
uv run agents/s05_skill_loading.py
uv run agents/s06_context_compact.py
uv run agents/s07_task_system.py
uv run agents/s08_background_tasks.py
uv run agents/s09_agent_teams.py
uv run agents/s10_team_protocols.py

Examples

s01_agent_loop.py

Basic agent that can execute bash commands and write files. Demonstrates the core tool-calling loop.

Try:

• "Create a file called hello.py that prints 'Hello, World!'"
• "List all Python files in this directory"

s02_tool_use.py

Safe file operations with workspace isolation. All file operations are restricted to the working directory.

Try:

• "Read the file hello.py"
• "Edit hello.py to change the message"

s03_todo_write.py

Agent with todo management and Nag Reminder. Tracks tasks and reminds itself to update the todo list when inactive.

Try:

• "Add tasks: create readme, write tests, commit code"
• "Mark the first task as in progress"

s04_subagent.py

Parent agent that spawns subagents for focused tasks. Subagents have fresh context and focused objectives.

s05_skill_loading.py

Dynamic skill loading from markdown files. Agent loads and uses specialized skills on-demand.

s06_context_compact.py

Three-layer context compaction strategy: micro (truncate tool results), meso (summarize turns), macro (restart with summary).

s07_task_system.py

Task graph management with JSON file persistence. Supports dependency tracking (blockedBy/blocks) and queries: ready, blocked, completed.

s08_background_tasks.py

Background daemon threads for parallel work. Long-running commands execute non-blocking; results queue for retrieval.

s09_agent_teams.py

Multi-agent teams with leader-worker pattern. Teammates run in daemon threads, communicate via JSONL file-based mailboxes.

Commands: /team (list members), /inbox (check leader inbox)

s10_team_protocols.py

Structured team protocols: graceful shutdown with acknowledgment, plan approval workflow with FSM-based request tracking.

Learning Resources

• Main Tutorial: learn-claude-agents.vercel.app - The primary source of this code
• Anthropic Docs: docs.anthropic.com

License

This is an educational project. Please refer to the original tutorial for licensing information.

Contributing

This is a learning project. Feel free to fork, experiment, and submit issues!