Changes

This PR introduces a comprehensive ReAct (Reasoning and Acting) agent implementation that operates independently of LangChain, providing a native Python ReAct pattern for MCP tool integration.
The implementation includes a complete ReAct execution engine, specialized adapters, type definitions, and comprehensive telemetry integration.

Implementation Details

1. ReAct Agent Architecture (mcp_use/agents/mcp_react_agent.py):
   - ReActExecutor: Core execution engine implementing the ReAct loop with structured LLM responses
   - MCPReActAgent: Main agent class compatible with MCPAgent interface
   - Supports both regular and streaming execution modes
   - Integrated conversation memory management with configurable turn limits
2. Type System (mcp_use/agents/types/react_agent_types.py):
   - ReActStep: Represents individual reasoning steps with automatic JSON parsing
   - ReActResponse: Structured LLM response format using Pydantic validation
   - ConversationMemory: Memory management with automatic history trimming
   - StepType: Enum for different step types (THOUGHT, ACTION, OBSERVATION, FINAL_ANSWER)
3. React Adapter (mcp_use/adapters/react_adapter.py):
   - ReactAdapter: Converts MCP tools/resources/prompts to callable ReactTool instances
   - Each tool gets an async execute function that handles MCP protocol communication
   - Supports resource-as-tool and prompt-as-tool conversion when enabled
   - Maintains connector-to-tool mapping for efficient caching
4. Enhanced LLM Client (mcp_use/llm/client.py):
   - Provider-agnostic LLM client using instructor for structured outputs
   - Supports OpenAI, Anthropic, and other providers through unified interface
   - Automatic async client initialization and model name normalization
5. MCP Capabilities (mcp_use/types/mcp.py):
   - Extended MCP type definitions with server capabilities modeling
   - Enhanced client methods for capability discovery and validation

Example Usage (Before)

  # Previously only LangChain-based agents were available
  from mcp_use.agents.mcpagent import MCPAgent

  agent = MCPAgent(
      model_name="gpt-4",
      client=mcp_client,
  )

Example Usage (After)

  # New ReAct agent with native Python implementation
  from mcp_use.agents.mcp_react_agent import MCPReActAgent, StepType

  # Create agent with direct MCP tool integration
  agent = MCPReActAgent(
      model_name="gpt-4o-mini",
      model_api_key=os.getenv("OPENAI_API_KEY"),
      client=mcp_client,
      max_steps=5,
      verbose=True,
      memory_enabled=True,
  )

  await agent.initialize()

  # Regular execution
  result = await agent.run("What tools do you have access to?")

Documentation Updates

• examples/react_agent_example.py: Comprehensive example demonstrating ReAct agent usage with server-everything
• Enhanced existing documentation in docstrings with detailed parameter descriptions
• Added type annotations throughout for better IDE support and code clarity

Testing

• Unit tests: Added comprehensive test coverage in tests/unit/test_llm_client.py for the new LLM client
• Integration tests: Added tests/integration/test_everything_server_capabilities.py for testing server capability discovery
• Manual testing: Verified with multiple MCP servers including server-everything
• Edge cases: Handled JSON parsing errors, tool execution failures, and memory management edge cases

Backwards Compatibility

These changes are fully backwards compatible. The existing MCPAgent (LangChain-based) remains unchanged and functional. The new MCPReActAgent is an alternative implementation that can be used alongside or instead of the existing agent without affecting current code.

Existing users can:

• Continue using MCPAgent without any changes
• Gradually migrate to MCPReActAgent for better performance and reduced dependencies
• Use both agents in the same application if needed