Simple Agent

A minimal, working example of an AI agent built with the Anthropic SDK. It shows the full tool use loop — Claude decides when to call a tool, your code executes it, and Claude uses the result to form a response — with conversation history that persists across sessions.

---

Features

• Tool use — Claude decides when to call add_numbers, executes it, and responds with the result
• Persistent memory — full conversation history saved to messages.json and restored on next run
• Clean loop — proper two-turn tool use pattern: tool_use → execute → tool_result → final response

---

How it works

You
 │
 ▼
Claude API ──► stop_reason: tool_use ──► Python executes tool
 │                                              │
 │◄──────────────── tool_result ───────────────┘
 │
 ▼
Claude API ──► stop_reason: end_turn ──► Final response

1. Your message is appended to the conversation history.
2. The full history is sent to Claude with the tool definitions.
3. If Claude wants to use a tool, it returns stop_reason: tool_use with the arguments.
4. Python executes the tool and sends the result back as a tool_result message.
5. Claude generates a final natural-language response.
6. Everything is saved to messages.json.

---

Getting started

Prerequisites: uv and an Anthropic API key

git clone https://github.com/iamMashel/simpleAgent.git
cd simpleAgent

Create a .env file:

ANTHROPIC_API_KEY=your_api_key_here

Install and run:

uv sync
uv run quickstart.py

Type exit to quit.

---

Example

💬 Chat loaded. Type 'exit' to quit.

You: what is 4 + 4
[tool] add_numbers({'a': 4.0, 'b': 4.0}) → 8.0
Claude: It's 8, which is just two 4s doing the fusion dance! 💃

You: what is a corn
Claude: A corn is a hard, painful bump on your foot that's basically your
skin's way of saying "hey, these shoes are a terrible life choice" 🌽👠

---

Project structure

simpleAgent/
├── quickstart.py   # Main chatbot with tool use
├── example2.py     # Earlier tool use iteration
├── pyproject.toml  # Dependencies
└── .env            # API key (not committed)

---

Dependencies

• anthropic — Claude API SDK
• python-dotenv — .env loading

---

License

MIT