The ReAct Pattern

# Tool definitions — what the agent can do
# The 'description' field is critical: the model 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.",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "The search query. Be specific — 'Mistral-7B context window size 2025' is better than 'Mistral 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.",
        "parameters": {
            "type": "object",
            "properties": {
                "url": {"type": "string", "description": "The full URL to fetch (must start with https://)"}
            },
            "required": ["url"]
        }
    }
]

from openai import OpenAI
import json

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

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 the model finishes (finish_reason == 'stop').
    max_turns is a SAFETY NET — the agent terminates via finish_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 ---
        # the model produces a thought, then optionally requests tool calls
        response = client.chat.completions.create(
            model="mistral",
            tools=TOOLS,
            messages=messages
        )

        msg = response.choices[0].message

        # --- STOP CHECK ---
        # finish_reason == "stop"       → model is done, extract final answer
        # finish_reason == "tool_calls" → model wants to call tools, continue loop
        if response.choices[0].finish_reason == "stop":
            return msg.content or "Agent finished without a text response."

        # Append the assistant's message (includes tool_calls) to history
        messages.append({
            "role": "assistant",
            "content": msg.content,
            "tool_calls": msg.tool_calls
        })

        # --- OBSERVE phase ---
        # Execute each tool call and append results as tool-role messages
        for tc in (msg.tool_calls or []):
            result = execute_tool(tc.function.name, json.loads(tc.function.arguments))
            messages.append({
                "role": "tool",
                "tool_call_id": tc.id,
                "content": result
            })

    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 (Mistral, GPT-4, Gemini, Claude)
"""
}

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 Mistral's tool use via Ollama.
"""
from openai import OpenAI
import json
import os
from mock_search import mock_search

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

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.",
        "parameters": {
            "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 finish_reason == 'stop'.

    Args:
        question: The user's research question
        max_turns: Safety cap (loop terminates via finish_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.chat.completions.create(
            model="mistral",
            tools=TOOLS,
            messages=messages
        )

        msg = response.choices[0].message

        # Print verbose trace
        if verbose:
            print(f"\n--- Turn {turn} (finish_reason: {response.choices[0].finish_reason}) ---")
            if msg.content:
                print(f"💭 {msg.content[:300]}{'...' if len(msg.content) > 300 else ''}")
            for tc in (msg.tool_calls or []):
                print(f"🔧 {tc.function.name}({tc.function.arguments[:100]})")

        # STOP: the model has produced its final answer
        if response.choices[0].finish_reason == "stop":
            return msg.content or "Agent completed without final text."

        # Append the assistant's message (with tool_calls) to history
        messages.append({
            "role": "assistant",
            "content": msg.content,
            "tool_calls": msg.tool_calls
        })

        # OBSERVE: Execute each tool call, append results as tool-role messages
        for tc in (msg.tool_calls or []):
            result = execute_tool(tc.function.name, json.loads(tc.function.arguments))
            if verbose:
                print(f"👁  Result preview: {result[:150]}...")
            messages.append({
                "role": "tool",
                "tool_call_id": tc.id,
                "content": result
            })

    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)