Agent Loop

This repository implements a reference agent loop on top of the Anthropic API. The agent controls its own execution flow through tool calls until it completes a task.

Core Components

• Agent (src/agent.py) - Runs the main loop: call Claude, execute tools, repeat until done
• StopCondition (src/stopping.py) - Configures when to stop (max iterations, tokens, required tools)
• RecoveryHandler (src/recovery.py) - Retries failed API calls with exponential backoff
• ConversationBuffer (src/memory/buffer.py) - Stores recent messages (sliding window)
• RetrievalMemory (src/memory/retrieval.py) - Stores long-term memories with semantic search
• MemoryAgent (src/agent_with_memory.py) - Agent with short-term and long-term memory

Examples

uv run examples/calculator_agent.py      # Math operations
uv run examples/research_agent.py        # Search and notes
uv run examples/file_agent.py            # File operations
uv run examples/memory_agent_example.py  # Memory persistence
uv run examples/advanced_config_agent.py # Custom stop/recovery config

Setup

uv sync
export ANTHROPIC_API_KEY=your_key

How It Works

1. User sends a task
2. Agent calls Claude with tools
3. Claude returns tool calls or text
4. Agent executes tools and feeds results back
5. Loop continues until Claude stops calling tools