Build Your First Agent in 60 Minutes

# Create your project directory
mkdir research-agent && cd research-agent

# Create isolated Python environment
python -m venv venv

# Activate it (Mac/Linux)
source venv/bin/activate

# Activate it (Windows)
# venv\Scripts\activate

# Install all dependencies
pip install anthropic requests beautifulsoup4 python-dotenv

# .env — DO NOT commit this file to git
ANTHROPIC_API_KEY=your-api-key-here

import requests
from bs4 import BeautifulSoup
import json

def search_web(query: str, num_results: int = 5) -> str:
    """Search using DuckDuckGo (no API key needed)"""
    try:
        url = f"https://html.duckduckgo.com/html/?q={query}"
        headers = {"User-Agent": "Mozilla/5.0 (research-agent/1.0)"}
        response = requests.get(url, headers=headers, timeout=10)
        soup = BeautifulSoup(response.text, 'html.parser')

        results = []
        for result in soup.find_all('div', class_='result', limit=num_results):
            title_tag = result.find('a', class_='result__a')
            snippet_tag = result.find('a', class_='result__snippet')
            url_tag = result.find('a', class_='result__url')

            if title_tag:
                results.append({
                    "title": title_tag.get_text(strip=True),
                    "url": url_tag.get_text(strip=True) if url_tag else "",
                    "snippet": snippet_tag.get_text(strip=True) if snippet_tag else ""
                })

        return json.dumps(results, indent=2)
    except Exception as e:
        return f"Search failed: {str(e)}"

def read_url(url: str) -> str:
    """Fetch and extract readable text from a URL"""
    try:
        headers = {"User-Agent": "Mozilla/5.0 (research-agent/1.0)"}
        response = requests.get(url, headers=headers, timeout=15)
        soup = BeautifulSoup(response.text, 'html.parser')

        # Remove navigation, footer, and scripts — they're noise
        for tag in soup(['script', 'style', 'nav', 'footer', 'header']):
            tag.decompose()

        text = soup.get_text(separator='\n', strip=True)
        # Limit to 3000 chars — enough content, won't blow the context window
        return text[:3000] + "..." if len(text) > 3000 else text
    except Exception as e:
        return f"Failed to read URL: {str(e)}"

# Tool definitions — these tell the Anthropic API what tools the agent has
TOOL_DEFINITIONS = [
    {
        "name": "search_web",
        "description": "Search the web for current information. Returns titles, URLs, and snippets.",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "Search query"},
                "num_results": {"type": "integer", "description": "Number of results (1-10)", "default": 5}
            },
            "required": ["query"]
        }
    },
    {
        "name": "read_url",
        "description": "Read the content of a specific URL. Use after search_web to get full article content.",
        "input_schema": {
            "type": "object",
            "properties": {
                "url": {"type": "string", "description": "The URL to read"}
            },
            "required": ["url"]
        }
    }
]

import anthropic
import os
from dotenv import load_dotenv
from tools import search_web, read_url, TOOL_DEFINITIONS

load_dotenv()
client = anthropic.Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))

SYSTEM_PROMPT = """You are a research agent. When given a topic, you:
1. Search for recent, authoritative sources using search_web
2. Read the most relevant ones in full using read_url
3. Synthesize the information from multiple sources
4. Write a comprehensive markdown report with:
   - Executive summary (3-5 sentences)
   - Key findings (bullet points)
   - Main trends and developments
   - Notable quotes or statistics with source attribution
   - Sources section with titles and URLs

Be thorough but concise. Prioritize sources from the last 12 months when possible.
Always read at least 2-3 full articles before writing your report."""

def execute_tool(name: str, inputs: dict) -> str:
    """Route a tool call request to the correct implementation"""
    if name == "search_web":
        return search_web(inputs["query"], inputs.get("num_results", 5))
    elif name == "read_url":
        return read_url(inputs["url"])
    return f"Unknown tool: {name}"

def run_research_agent(topic: str, max_iterations: int = 15) -> str:
    """Run the research agent on a given topic and return a markdown report"""
    print(f"\n Researching: {topic}")
    print("-" * 50)

    # Start conversation with the user's research request
    messages = [{
        "role": "user",
        "content": f"Research this topic and write a comprehensive report: {topic}"
    }]
    iteration = 0

    while iteration < max_iterations:
        iteration += 1
        print(f"\n[Iteration {iteration}]")

        # Send messages to the model
        response = client.messages.create(
            model="claude-opus-4-6",
            max_tokens=4096,
            system=SYSTEM_PROMPT,
            tools=TOOL_DEFINITIONS,
            messages=messages
        )

        print(f"  Stop reason: {response.stop_reason}")

        if response.stop_reason == "end_turn":
            # Model finished — extract the final text response
            for block in response.content:
                if hasattr(block, 'text'):
                    return block.text
            return "Research complete (no text output generated)"

        if response.stop_reason == "tool_use":
            # Model wants to use tools — add its response to history
            messages.append({"role": "assistant", "content": response.content})

            # Execute every tool the model requested
            tool_results = []
            for block in response.content:
                if block.type == "tool_use":
                    print(f"   {block.name}: {str(block.input)[:80]}...")
                    result = execute_tool(block.name, block.input)
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": result
                    })

            # Return all tool results to the model and loop again
            messages.append({"role": "user", "content": tool_results})

    return "Max iterations reached. The partial research above may be incomplete."

import sys
from agent import run_research_agent

def main():
    # Accept topic from command line args or prompt interactively
    if len(sys.argv) < 2:
        topic = input("Enter research topic: ")
    else:
        topic = " ".join(sys.argv[1:])

    # Run the agent
    report = run_research_agent(topic)

    # Save the report as a markdown file
    filename = f"report_{topic[:30].replace(' ', '_')}.md"
    with open(filename, 'w') as f:
        f.write(report)

    print(f"\n Report saved to: {filename}")
    print("\n" + "="*50)
    print(report[:500] + "...")

if __name__ == "__main__":
    main()

python main.py "quantum computing breakthroughs 2024"