The ReAct Pattern

# Tool definitions — what the agent can do
# The 'description' field is critical: Claude reads it to decide WHEN to call this tool
TOOLS = [
    {
        "name": "web_search",
        "description": "Search the web for current information. Use for: facts that may have changed since training, recent events, prices, statistics. Do NOT use for: well-known stable facts (capitals, basic science), things you already know.",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "The search query. Be specific — 'Claude 3.5 Sonnet context window 2025' is better than 'Claude context window'."
                }
            },
            "required": ["query"]
        }
    },
    {
        "name": "read_url",
        "description": "Fetch and return the text content of a web page. Use after web_search when you need the full article, not just the snippet.",
        "input_schema": {
            "type": "object",
            "properties": {
                "url": {"type": "string", "description": "The full URL to fetch (must start with https://)"}
            },
            "required": ["url"]
        }
    }
]

import anthropic
import json

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from environment

SYSTEM_PROMPT = """You are a research assistant with access to web search tools.

Before calling ANY tool, write a Thought: explaining:
1. What you currently know about the question
2. What specific information you still need
3. Why this particular tool call will fill that gap

After receiving a tool result, write another Thought: summarizing what you learned
and whether you need more information or can now answer the question.

This reasoning process makes your answers more accurate and your actions more focused."""


def run_react_agent(user_question: str, max_turns: int = 20) -> str:
    """
    Run the ReAct loop until Claude finishes (stop_reason == 'end_turn').
    max_turns is a SAFETY NET — the agent terminates via stop_reason, not via this cap.
    """
    messages = [{"role": "user", "content": user_question}]
    turn_count = 0

    while turn_count < max_turns:
        turn_count += 1

        # --- REASON + ACT phase ---
        # Claude produces a thought, then optionally requests a tool call
        response = client.messages.create(
            model="claude-opus-4-7",
            max_tokens=4096,
            system=SYSTEM_PROMPT,
            tools=TOOLS,
            messages=messages
        )

        # Append Claude's full response to history (preserves thought traces + tool calls)
        messages.append({"role": "assistant", "content": response.content})

        # --- STOP CHECK ---
        # 'end_turn' = Claude is done and produced a final answer
        # 'tool_use' = Claude wants to call one or more tools
        if response.stop_reason == "end_turn":
            # Extract the final text response
            for block in response.content:
                if hasattr(block, 'text'):
                    return block.text
            return "Agent finished without a text response."

        # --- OBSERVE phase ---
        # Find all tool_use blocks Claude requested and execute them
        tool_results = []
        for block in response.content:
            if block.type == "tool_use":
                result = execute_tool(block.name, block.input)
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result
                })

        # Append all tool results so Claude can observe them in the next turn
        if tool_results:
            messages.append({"role": "user", "content": tool_results})

    return f"Safety limit reached after {max_turns} turns."


def execute_tool(name: str, inputs: dict) -> str:
    """Dispatch tool calls to their implementations."""
    try:
        if name == "web_search":
            return web_search(inputs["query"])
        elif name == "read_url":
            return read_url(inputs["url"])
        else:
            return json.dumps({"error": f"Unknown tool: {name}", "isError": True})
    except Exception as e:
        # Always return structured errors — never raise. The agent decides what to do next.
        return json.dumps({"error": str(e), "tool": name, "isError": True})

"""
Mock search tool — simulates web_search results for development.
Swap for httpx + real search API in production.
"""

MOCK_RESULTS = {
    "python ai frameworks 2025": """
Top Python AI/Agent Frameworks 2025:
1. LangChain — most ecosystem integrations, complex but powerful
2. LlamaIndex — best for RAG and document processing
3. CrewAI — multi-agent orchestration, growing fast
4. claude-agent-sdk — Anthropic's first-party SDK for Claude agents
5. AutoGen (Microsoft) — enterprise-focused, code execution focus

Trend: First-party SDKs (claude-agent-sdk, OpenAI Agents SDK) are gaining vs wrapper frameworks.
""",
    "claude agent sdk features": """
claude-agent-sdk v1.2 Features (May 2025):
- @tool decorator for typed async tool functions
- query() for single-agent invocation
- ClaudeAgentOptions: model, system_prompt, tools, max_turns, hooks
- Built-in: can_use_tool hook for fine-grained control
- create_sdk_mcp_server() for MCP server creation
- Native subagent support via .claude/agents/ directory
- Streaming support with async generators
""",
    "react pattern llm agents": """
ReAct (Reasoning + Acting) — Yao et al. 2022:
- Interleaves reasoning traces with tool calls
- Shows 10-40% improvement on knowledge-intensive benchmarks vs silent tool use
- Key principle: thought before action improves tool selection accuracy
- Adopted by: LangChain, LlamaIndex, AutoGen as default agent pattern
- Works with any LLM supporting tool use (Claude, GPT-4, Gemini)
"""
}

def mock_search(query: str) -> str:
    """Return mock search results for the given query."""
    query_lower = query.lower()
    # Find best matching mock result
    for key, result in MOCK_RESULTS.items():
        if any(word in query_lower for word in key.split()):
            return f"Search results for '{query}':\n{result}"
    return f"Search results for '{query}':\nNo specific results found. General information: {query} is an active research area in AI. Recent developments include improved tooling and better benchmark performance."

"""
ReAct Research Agent — M12 hands-on lab
Demonstrates the Reason → Act → Observe loop using Claude's tool use.
"""
import anthropic
import json
import os
from mock_search import mock_search

client = anthropic.Anthropic()

SYSTEM_PROMPT = """You are a research assistant that compiles accurate, well-sourced reports.

IMPORTANT: Before EVERY tool call, write:
  Thought: [your reasoning — what you know, what's missing, why THIS tool call]

After EVERY tool result, write:
  Thought: [what you learned and whether you need more information]

When you have enough information, produce a structured report with:
- Summary (2-3 sentences)
- Key Findings (bullet points)
- Sources Used (list the searches you ran)"""

TOOLS = [
    {
        "name": "web_search",
        "description": "Search the web for current information about AI, technology, or research topics. Use specific queries for better results.",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "Search query — be specific (e.g., 'claude agent sdk features 2025' not 'claude')"
                }
            },
            "required": ["query"]
        }
    }
]


def execute_tool(name: str, inputs: dict) -> str:
    """Dispatch a tool call to its implementation."""
    if name == "web_search":
        return mock_search(inputs.get("query", ""))
    return json.dumps({"error": f"Unknown tool: {name}", "isError": True})


def run_agent(question: str, max_turns: int = 20, verbose: bool = True) -> str:
    """
    Run the ReAct loop until stop_reason == 'end_turn'.

    Args:
        question: The user's research question
        max_turns: Safety cap (loop terminates via stop_reason, not this cap)
        verbose: Print thought traces and tool calls to stdout
    """
    messages = [{"role": "user", "content": question}]
    turn = 0

    if verbose:
        print(f"\n{'='*60}")
        print(f"QUESTION: {question}")
        print('='*60)

    while turn < max_turns:
        turn += 1

        response = client.messages.create(
            model="claude-opus-4-7",
            max_tokens=4096,
            system=SYSTEM_PROMPT,
            tools=TOOLS,
            messages=messages
        )

        # Append Claude's full response (includes both text thoughts and tool_use blocks)
        messages.append({"role": "assistant", "content": response.content})

        # Print verbose trace
        if verbose:
            print(f"\n--- Turn {turn} (stop_reason: {response.stop_reason}) ---")
            for block in response.content:
                if hasattr(block, 'text') and block.text:
                    print(f"💭 {block.text[:300]}{'...' if len(block.text) > 300 else ''}")
                elif block.type == "tool_use":
                    print(f"🔧 {block.name}({json.dumps(block.input, indent=None)[:100]})")

        # STOP: Claude has produced its final answer
        if response.stop_reason == "end_turn":
            for block in response.content:
                if hasattr(block, 'text') and block.text:
                    return block.text
            return "Agent completed without final text."

        # OBSERVE: Execute tool calls, collect results
        tool_results = []
        for block in response.content:
            if block.type == "tool_use":
                result = execute_tool(block.name, block.input)
                if verbose:
                    print(f"👁  Result preview: {result[:150]}...")
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result
                })

        if tool_results:
            messages.append({"role": "user", "content": tool_results})

    return f"[Safety cap reached after {max_turns} turns — partial result]"


if __name__ == "__main__":
    question = "What are the main Python frameworks for building AI agents in 2025, and how does the claude-agent-sdk compare to them?"
    answer = run_agent(question, verbose=True)
    print("\n" + "="*60)
    print("FINAL REPORT:")
    print("="*60)
    print(answer)