How to Build an AI Agent with Claude (The Real Pattern)

#claudecode #ai #python #tutorial

How to Build an AI Agent with Claude (The Real Pattern)

Most AI agents are just chatbots with a longer system prompt. A real agent executes tasks autonomously — reads files, calls APIs, makes decisions, and takes actions without input at every step.

What Makes Something an Agent

The defining characteristic: the agent decides what to do next based on current state, not waiting for human instruction each step.

Minimal agent loop:

Observe current state (read files, call APIs, check logs)
Decide what action to take
Execute the action
Observe the result
Repeat until goal achieved or blocked

The Simplest Agent: Claude With Tools

import anthropic
import subprocess, os

client = anthropic.Anthropic()

tools = [
    {
        "name": "run_shell",
        "description": "Run a shell command and return output",
        "input_schema": {
            "type": "object",
            "properties": {"command": {"type": "string"}},
            "required": ["command"],
        },
    },
    {
        "name": "write_file",
        "description": "Write content to a file",
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {"type": "string"},
                "content": {"type": "string"},
            },
            "required": ["path", "content"],
        },
    },
]

def execute_tool(name, inp):
    if name == "run_shell":
        r = subprocess.run(inp["command"], shell=True,
                           capture_output=True, text=True, timeout=30)
        return r.stdout + r.stderr
    if name == "write_file":
        os.makedirs(os.path.dirname(inp["path"]) or ".", exist_ok=True)
        open(inp["path"], "w").write(inp["content"])
        return f'Written: {inp["path"]}'
    return f"Unknown tool: {name}"

def run_agent(goal: str, max_iter: int = 10):
    messages = [{"role": "user", "content": goal}]

    for i in range(max_iter):
        resp = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=4096,
            tools=tools,
            messages=messages,
        )
        messages.append({"role": "assistant", "content": resp.content})

        if resp.stop_reason == "end_turn":
            return next((b.text for b in resp.content if hasattr(b, "text")), "")

        results = []
        for block in resp.content:
            if block.type == "tool_use":
                print(f"  Tool: {block.name}")
                out = execute_tool(block.name, block.input)
                results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": out,
                })
        messages.append({"role": "user", "content": results})

    return "Max iterations reached"

# Run it
result = run_agent(
    "List Python files in the current directory, read the largest one, "
    "and write a 3-sentence summary to summary.md"
)
print(result)

The Agent Loop Explained

Why max_iter? Without a ceiling, a confused agent loops forever. 10-20 iterations covers almost every real task; if it takes more, something is wrong.

Why check stop_reason == 'end_turn'? Claude signals it's done by stopping without tool calls. Any other stop reason means it wants to keep working.

Why append tool results as a user message? The MCP protocol requires it. Tool results are the 'observation' step in the observe-decide-act loop.

Adding Persistence Between Runs

For agents that work across multiple sessions, persist state:

import json
from pathlib import Path

STATE_FILE = Path('.agent-state.json')

def load_state():
    if STATE_FILE.exists():
        return json.loads(STATE_FILE.read_text())
    return {'completed_tasks': [], 'current_goal': None}

def save_state(state):
    STATE_FILE.write_text(json.dumps(state, indent=2))