Build your first AI agent with Python and the Claude API

Step 3: close the loop

To finish the job you must run the tool, then send the answer back as a tool_result that quotes the request's ID. Then Claude may answer, or ask for another tool. So we wrap the whole thing in a loop.

First, a small dispatcher that matches a tool name to a function:

def run_tool(name, tool_input):
    if name == "calculator":
        return calculator(**tool_input)
    return f"Error: unknown tool {name}"

And now the agent itself:

MAX_STEPS = 8

def run_agent(question):
    messages = [{"role": "user", "content": question}]

    for _ in range(MAX_STEPS):
        response = client.messages.create(
            model=MODEL,
            max_tokens=4000,
            tools=TOOLS,
            messages=messages,
        )
        messages.append(
            {"role": "assistant", "content": response.content}
        )

        if response.stop_reason != "tool_use":
            return "".join(
                b.text for b in response.content
                if b.type == "text"
            )

        results = []
        for block in response.content:
            if block.type == "tool_use":
                output = run_tool(block.name, block.input)
                results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": output,
                })
        messages.append({"role": "user", "content": results})

    return "Stopped: the agent took too many steps."

Read it top to bottom:

• We keep a messages list, because the API remembers nothing between calls. Every request carries the whole conversation.
• After each reply we add Claude's full answer to the list. Keep it exactly as it came back, because Claude may include extra blocks, such as its own thinking, that it needs to see again.
• If stop_reason isn't tool_use, Claude is done, so we return its text.
• Otherwise we run every tool it asked for and send all the results back in a single user message, each tagged with the matching tool_use_id.
• MAX_STEPS is a safety net. An agent in a loop that costs money should always have a limit.

Try it: print(run_agent("What is 120 / 15?")).

Step 4: add a second tool

Here's the nice part. Adding a capability doesn't touch the loop at all. Add a description to the TOOLS list:

    {
        "name": "read_notes",
        "description": (
            "Read the student's study notes. Takes no "
            "input. Use it when the student asks about "
            "their notes, plans or deadlines."
        ),
        "input_schema": {"type": "object", "properties": {}},
    },

Then the function, and one new check in run_tool:

from pathlib import Path

NOTES_FILE = Path("notes.txt")

def read_notes():
    if not NOTES_FILE.exists():
        return "Error: notes.txt was not found"
    return NOTES_FILE.read_text(encoding="utf-8")

    if name == "read_notes":
        return read_notes()

This tool is safe by design: it can only read one fixed file. It can't be told to open anything else, because Claude supplies no file path. Keep your tools that narrow.

The full script

Here's everything together. Save it as study_agent.py:

import sys
from pathlib import Path

import anthropic

MODEL = "claude-haiku-5-5"
NOTES_FILE = Path("notes.txt")
MAX_STEPS = 8

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY

SYSTEM = (
    "You are a friendly study helper. Use the calculator for "
    "any arithmetic and read_notes when the student mentions "
    "their notes. Keep answers short and clear."
)

TOOLS = [
    {
        "name": "calculator",
        "description": (
            "Do basic arithmetic on two numbers. Use this for "
            "any sum, difference, product or division instead "
            "of working it out yourself."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "operation": {
                    "type": "string",
                    "enum": ["add", "subtract", "multiply", "divide"],
                },
                "a": {"type": "number"},
                "b": {"type": "number"},
            },
            "required": ["operation", "a", "b"],
        },
    },
    {
        "name": "read_notes",
        "description": (
            "Read the student's study notes from their notes "
            "file. Takes no input. Use it when the student "
            "asks about their notes, plans or deadlines."
        ),
        "input_schema": {"type": "object", "properties": {}},
    },
]


def calculator(operation, a, b):
    if operation == "add":
        return str(a + b)
    if operation == "subtract":
        return str(a - b)
    if operation == "multiply":
        return str(a * b)
    if operation == "divide":
        if b == 0:
            return "Error: cannot divide by zero"
        return str(a / b)
    return f"Error: unknown operation {operation}"


def read_notes():
    if not NOTES_FILE.exists():
        return "Error: notes.txt was not found"
    return NOTES_FILE.read_text(encoding="utf-8")


def run_tool(name, tool_input):
    if name == "calculator":
        return calculator(**tool_input)
    if name == "read_notes":
        return read_notes()
    return f"Error: unknown tool {name}"


def run_agent(question):
    messages = [{"role": "user", "content": question}]

    for _ in range(MAX_STEPS):
        response = client.messages.create(
            model=MODEL,
            max_tokens=4000,
            system=SYSTEM,
            tools=TOOLS,
            messages=messages,
        )
        messages.append(
            {"role": "assistant", "content": response.content}
        )

        if response.stop_reason != "tool_use":
            return "".join(
                b.text for b in response.content
                if b.type == "text"
            )

        results = []
        for block in response.content:
            if block.type == "tool_use":
                print(f"  [tool] {block.name} {block.input}")
                output = run_tool(block.name, block.input)
                results.append(
                    {
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": output,
                    }
                )
        messages.append({"role": "user", "content": results})

    return "Stopped: the agent took too many steps."


if __name__ == "__main__":
    question = " ".join(sys.argv[1:]) or (
        "Read my notes and tell me how many days I need."
    )
    print(run_agent(question))

Two small additions here: a SYSTEM prompt that sets the agent's job, and a print line that shows each tool call as it happens, so you can watch the agent work.

Run it:

python study_agent.py "Read my notes and tell me how many days I need."

You should see Claude call read_notes, then calculator with 120 divided by 15, then reply that you need 8 days. Exact wording will vary, as it does with any AI.

Ideas to extend it

Once the loop makes sense, everything else is more tools:

• A date tool. Return today's date so it can count days to an exam. datetime.date.today() is all you need.
• A flashcard tool that appends a question and answer to a text file you choose in advance.
• A quiz mode that reads your notes and asks you questions, using a longer system prompt.
• Memory. Wrap run_agent in a loop that keeps messages between questions, so it remembers the chat.

When you add a tool that changes anything, such as writing a file, keep it narrow and fixed in what it can touch.

The shortcut, once you understand the loop

You wrote the loop by hand so you'd see how it works. The Python SDK also has a built-in tool runner that runs this loop for you from decorated functions. Anthropic's tool runner docs cover it. It's a good next step, but it's far less confusing once you've written the manual version.

Common errors and fixes

• AuthenticationError, or a message about missing authentication. The API key isn't set in this terminal. Environment variables last only for the window you set them in. Set it again and re-run.
• NotFoundError mentioning the model. Check the model ID for typos. It should be exactly claude-haiku-5-5, with no date on the end.
• A billing or credit error. Add credit in the Console. Chat subscriptions don't cover API use.
• BadRequestError about a tool_use with no tool_result. Every tool_use block needs a matching tool_result in your next message. Make sure you reply to all of them, in one message.
• The agent never calls a tool. Your description is too vague. Say what the tool does and when to use it.
• "Stopped: the agent took too many steps." Your safety net worked. Print the tool calls to see where it got stuck.
• python isn't recognised on Windows. Try py instead, or reinstall Python and tick "Add to PATH".

You now have the same skeleton that powers far bigger agents: a model, some tools and a loop. The rest is mostly deciding what tools are worth giving it.