Understanding
Agents

mkdir -p agent-lab && cd agent-lab
python -m venv .venv
source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install anthropic python-dotenv
echo "ANTHROPIC_API_KEY=your_key_here" > .env

import os
import anthropic
from dotenv import load_dotenv

load_dotenv()
client = anthropic.Anthropic()

# The system prompt enforces ReAct: think before every action
SYSTEM = """You are a research agent that follows the ReAct pattern strictly.
Before every tool call, write a Thought explaining your reasoning.
After receiving a tool result, write an Observation summarising what you learned.
Keep thinking and acting until you have enough information to give a complete answer.
When you are done, write your final answer clearly."""

# Two tools: simulated search and a word counter
TOOLS = [
    {
        "name": "web_search",
        "description": (
            "Search the web for information on a topic. "
            "Returns a short summary of the top result. "
            "Use this when you need factual information you don't know."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "The search query"
                }
            },
            "required": ["query"]
        }
    },
    {
        "name": "count_words",
        "description": "Counts the number of words in a given text string.",
        "input_schema": {
            "type": "object",
            "properties": {
                "text": {
                    "type": "string",
                    "description": "The text to count words in"
                }
            },
            "required": ["text"]
        }
    }
]

# Simulated search DB — swap for a real search API in production
SEARCH_DB = {
    "ReAct paper": (
        "ReAct: Synergizing Reasoning and Acting in Language Models. "
        "Yao et al., arXiv:2210.03629, published at ICLR 2023. "
        "Interleaves chain-of-thought reasoning with action steps."
    ),
    "LangGraph": (
        "LangGraph is a library for building stateful, multi-actor applications with LLMs. "
        "Built by LangChain. Uses a graph of nodes and edges to model agent workflows. "
        "Supports cycles, branching, and human-in-the-loop patterns."
    ),
    "Anthropic": (
        "Anthropic is an AI safety company founded in 2021. "
        "Creators of the Claude model family. Developed Constitutional AI (CAI). "
        "Focused on AI safety research and interpretability."
    ),
}

def web_search(query: str) -> str:
    for key, result in SEARCH_DB.items():
        if key.lower() in query.lower():
            return result
    return f'No results found for "{query}". Try a different query.'


def count_words(text: str) -> str:
    count = len(text.split())
    return f"Word count: {count}"


def execute_tool(name: str, tool_input: dict) -> str:
    if name == "web_search":
        return web_search(tool_input["query"])
    if name == "count_words":
        return count_words(tool_input["text"])
    return f"Unknown tool: {name}"

def run_react_agent(user_message: str, max_iterations: int = 8) -> str:
    messages = [{"role": "user", "content": user_message}]
    total_input_tokens = 0

    print(f"\n{'='*60}")
    print(f"USER: {user_message}")
    print(f"{'='*60}")

    for iteration in range(max_iterations):
        print(f"\n[iteration {iteration + 1}]")

        response = client.messages.create(
            model="claude-opus-4-6",  # check docs.anthropic.com for current models
            max_tokens=1024,
            system=SYSTEM,
            tools=TOOLS,
            messages=messages
        )

        total_input_tokens += response.usage.input_tokens
        print(f"  stop_reason  : {response.stop_reason}")
        print(f"  input_tokens : {response.usage.input_tokens} (total: {total_input_tokens})")

        # Print the full reasoning trace from this iteration
        for block in response.content:
            if hasattr(block, "text") and block.text.strip():
                print(f"\n  THOUGHT/TEXT:\n  {block.text.strip()}")
            elif block.type == "tool_use":
                print(f"\n  ACTION: {block.name}({block.input})")

        # Append assistant turn to history
        messages.append({"role": "assistant", "content": response.content})

        # Done
        if response.stop_reason == "end_turn":
            for block in response.content:
                if hasattr(block, "text"):
                    print(f"\n{'='*60}")
                    print(f"FINAL ANSWER:\n{block.text}")
                    print(f"{'='*60}")
                    print(f"Total input tokens used: {total_input_tokens}")
                    return block.text
            return "(end_turn with no text)"

        # Execute tool calls, collect observations
        if response.stop_reason == "tool_use":
            tool_results = []
            for block in response.content:
                if block.type == "tool_use":
                    result = execute_tool(block.name, block.input)
                    print(f"  OBSERVATION: {result}")
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": result
                    })
            messages.append({"role": "user", "content": tool_results})

    return "Max iterations reached."


if __name__ == "__main__":
    run_react_agent(
        "Search for the ReAct paper, then count how many words "
        "are in the result you find."
    )

python react_agent.py

============================================================
USER: Search for the ReAct paper, then count how many words are in the result.
============================================================

[iteration 1]
  stop_reason  : tool_use
  input_tokens : 612 (total: 612)

  THOUGHT/TEXT:
  I'll search for the ReAct paper first.

  ACTION: web_search({'query': 'ReAct paper'})
  OBSERVATION: ReAct: Synergizing Reasoning and Acting in Language Models.
               Yao et al., arXiv:2210.03629, published at ICLR 2023.
               Interleaves chain-of-thought reasoning with action steps.

[iteration 2]
  stop_reason  : tool_use
  input_tokens : 743 (total: 1355)

  THOUGHT/TEXT:
  I found the ReAct paper. Now I'll count the words in that result.

  ACTION: count_words({'text': 'ReAct: Synergizing Reasoning ...'})
  OBSERVATION: Word count: 30

[iteration 3]
  stop_reason  : end_turn
  input_tokens : 821 (total: 2176)

  THOUGHT/TEXT:
  I have all the information needed to answer.

============================================================
FINAL ANSWER:
The ReAct paper (Yao et al., arXiv:2210.03629, ICLR 2023) describes a pattern
that interleaves chain-of-thought reasoning with action steps. The search result
summary contains 30 words.
============================================================
Total input tokens used: 2176

{
    "name": "get_current_date",
    "description": "Returns today's date in ISO 8601 format (YYYY-MM-DD).",
    "input_schema": {"type": "object", "properties": {}}
}

from datetime import date

if name == "get_current_date":
    return str(date.today())

run_react_agent("What is today's date, and search for 'quantum computing'.")