Building Your First Agent

Resist the temptation to put everything in one file. Separating tool implementations, tool schemas, and the agent loop pays dividends the moment you need to debug why the agent chose the wrong tool or passed the wrong argument. The structure below treats tools as ordinary Python functions that can be unit tested independently, before the agent loop ever runs.

Schemas are declared in their own file so you can update a description without touching the implementation. The agent loop in agent.py contains no business logic: it only drives the conversation between the model and the tools.

research-agent/
├── .env                    # API keys (never commit)
├── .gitignore
├── requirements.txt
├── src/
│   ├── agent.py            # Agent loop only
│   ├── tools.py            # Tool implementations
│   ├── schemas.py          # Tool schemas for the API
│   └── utils.py            # Logging helpers
└── tests/
    ├── test_tools.py       # Unit tests per tool
    └── test_agent.py       # Integration test

Tools are ordinary Python functions. Build and test them completely before connecting them to the agent loop. This matters because a broken tool produces a confusing mid-run result, whereas a failing unit test tells you immediately which function is wrong and why.

One safety rule applies to every tool that evaluates expressions: never pass model-generated strings to Python's built-in eval(). The model generates tool arguments. A prompt injection attack could cause the model to generate a malicious expression. Use a restricted evaluator such as simpleeval (available via pip) that allows only arithmetic operations, blocking file access and imports entirely.

Write unit tests for each tool independently. Run them before you start the agent loop. This isolates failures and shortens feedback cycles dramatically.

# tests/test_tools.py
import pytest
from src.tools import search_web, calculate, write_report

def test_calculate_addition():
    result = calculate("2 + 2")
    assert result["result"] == 4

def test_calculate_malformed_expression():
    result = calculate("not_a_number + 5")
    assert "error" in result

def test_write_report_structure():
    result = write_report(
        title="Test Report",
        sections=[{"heading": "Introduction", "content": "Content here."}]
    )
    assert "# Test Report" in result["report"]
    assert result["sections"] == 1

The tool schema is what the model reads to decide whether and how to call a tool. Vague descriptions produce wrong tool selection. Missing parameter descriptions produce wrong arguments. Schema quality determines agent behaviour more directly than any system prompt trick.

Two description patterns matter most. First, say what the tool is for and what it is not for: "Search the web for current information. Do not use for calculations." Second, include a sequencing hint on completion tools: "Use this as the final step after all searches are complete. Do not call until research is finished." Without that signal, the agent has no clear completion condition.

# src/schemas.py
TOOL_SCHEMAS = [
    {
        "name": "search_web",
        "description": "Search the web for current information. Use this when you need facts or recent news. Do not use for calculations.",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "A specific, focused search query. Use precise terms."
                }
            },
            "required": ["query"]
        }
    },
    {
        "name": "write_report",
        "description": "Compile research into a structured report. Use this as the FINAL step after all searches are done. Do not call until research is complete.",
        "input_schema": {
            "type": "object",
            "properties": {
                "title": {"type": "string"},
                "sections": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "heading": {"type": "string"},
                            "content": {"type": "string"}
                        }
                    }
                }
            },
            "required": ["title", "sections"]
        }
    }
]

The agent loop has three states: the model generates a final response (stop_reason == "end_turn"), the model requests tool calls (stop_reason == "tool_use"), or the safety step limit is reached. Every production agent needs all three states handled explicitly.

Set MAX_STEPS as a hard limit before you begin. Without it, a misbehaving agent can loop indefinitely, consuming tokens and incurring costs until you manually terminate the process.

# src/agent.py
import json, logging, anthropic
from src.tools import search_web, calculate, write_report
from src.schemas import TOOL_SCHEMAS
from dotenv import load_dotenv

load_dotenv()
logger = logging.getLogger(__name__)
client = anthropic.Anthropic()

TOOL_REGISTRY = {
    "search_web": search_web,
    "calculate": calculate,
    "write_report": write_report
}
MAX_STEPS = 15

def run_agent(user_request: str) -> str:
    messages = [{"role": "user", "content": user_request}]
    step = 0

    while step < MAX_STEPS:
        step += 1
        logger.info(f"Step {step}/{MAX_STEPS}")
        response = client.messages.create(
            model="claude-opus-4-6",
            max_tokens=2048,
            system="You are a research assistant...",
            tools=TOOL_SCHEMAS,
            messages=messages
        )
        logger.info(f"Stop reason: {response.stop_reason}")

        if response.stop_reason == "end_turn":
            text_blocks = [b for b in response.content if hasattr(b, 'text')]
            return text_blocks[0].text if text_blocks else "Task completed."

        if response.stop_reason == "tool_use":
            messages.append({"role": "assistant", "content": response.content})
            tool_results = []
            for block in response.content:
                if block.type != "tool_use":
                    continue
                logger.info(f"Tool call: {block.name}")
                fn = TOOL_REGISTRY.get(block.name)
                if fn:
                    try:
                        result = fn(**block.input)
                    except Exception as exc:
                        result = {"error": f"{type(exc).__name__}: {str(exc)}"}
                else:
                    result = {"error": f"Unknown tool: {block.name}"}
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": json.dumps(result)
                })
            messages.append({"role": "user", "content": tool_results})

    return "Unable to complete the task within the step limit."}

Structured logging turns an opaque agent run into a readable decision trace. Log the step number, the stop reason, the tool name, and the result keys returned. Reading this sequence tells you whether the agent is choosing the right tools, passing sensible arguments, and making progress toward the goal.

When the agent loops to the step limit without producing a result, inspect the last three tool calls. The most common causes: a completion condition the model cannot satisfy (rewrite the system prompt to clarify what "done" means); a tool returning an error the model interprets as a reason to keep searching; two tools with overlapping descriptions causing the model to alternate between them.