ClaudeSample

A sample project demonstrating how to use the Anthropic Claude API with Python, managed with uv.

Quick Start

Prerequisites

• Python 3.14+
• uv — fast Python package manager

Install uv if you don't have it:

https://docs.astral.sh/uv/getting-started/installation/

Setup

1. Clone and install dependencies:

   uv sync

2. Configure your API credentials:

   Copy the example env file and fill in your values:

   cp .env.example .env

   Edit .env with your Anthropic API details:

   ANTHROPIC_AUTH_TOKEN=your-api-key-here
   ANTHROPIC_BASE_URL=your-custom-base-url
   

   Alternatively, set the standard ANTHROPIC_API_KEY environment variable — the SDK picks it up automatically.

Running the Samples

Basic API Call

Send a simple message to Claude:

uv run basic-api/basic.py

This creates a client.messages.create call and prints Claude's response — a list of TextBlock objects.

Tool Use

See how Claude can call external tools (like a weather lookup):

uv run tooluse/tooluse.py

This demonstrates the tool-use pattern:

1. Define a tool schema (get_weather with a city parameter)
2. Send a message with the tool available
3. If Claude returns a tool_use block, execute the tool and feed the result back
4. Claude uses the result to produce its final answer

# Define a tool Claude can use
tools: list[ToolParam] = [
    {
        "name": "get_weather",
        "description": "Get weather for a city.",
        "input_schema": {
            "type": "object",
            "properties": {"city": {"type": "string", "description": "City name"}},
            "required": ["city"],
        },
    }
]

# If Claude wants to use a tool:
if response.stop_reason == "tool_use":
    tool = [b for b in response.content if b.type == "tool_use"][0]
    # ... run the tool, then send result back

Interactive Visual Guide

Open tooluse/tool-use-flow.html in your browser for an interactive, step-by-step visual guide on how AI agents use tools — from detecting intent to executing tools and returning results.

open tooluse/tool-use-flow.html   # macOS
xdg-open tooluse/tool-use-flow.html  # Linux

Adding Dependencies

Use uv add to install new packages:

uv add anthropic          # already installed
uv add python-dotenv      # already installed
uv add <package-name>     # add any new package

Project Structure

├── basic-api/
│   └── basic.py            # Simple Claude API message call
├── tooluse/
│   ├── tooluse.py          # Tool-use example (get_weather)
│   └── tool-use-flow.html  # Interactive visual guide to tool use
├── main.py                 # Project entry point
├── pyproject.toml          # uv project definition
├── .env.example            # Environment variable template
└── .python-version         # Python version pin

UV Cheat Sheet

Task	Command
Install dependencies	uv sync
Add a package	uv add <package>
Run a script	uv run <path>
Open a shell with deps	uv venv && source .venv/bin/activate
Update dependencies	uv lock --upgrade