agents.react¶

ReactAgent Package - Reasoning and Acting AI Agents with Tool Integration.

This package provides the ReactAgent, an advanced AI agent that implements the ReAct (Reasoning and Acting) pattern for tool-based problem solving, complex reasoning, and iterative task execution with real-time decision making.

The ReactAgent extends beyond simple conversation to provide: - Tool Integration: Seamless integration with external tools and APIs - Reasoning Loops: Iterative thought-action-observation cycles - Planning Capabilities: Multi-step reasoning and task decomposition - Error Handling: Robust error recovery and alternative strategy execution - Structured Output: Type-safe result generation with validation

Core Architecture:

ReactAgent implements the ReAct pattern through several key components:

Reasoning Engine:

Iterative thought-action-observation loops for complex problem solving
Multi-step reasoning with intermediate result validation
Dynamic strategy adaptation based on tool execution results
Reflection and self-correction capabilities for improved accuracy

Tool Management System:

Dynamic tool registration and execution
Tool routing and selection based on task requirements
Error handling and fallback strategies for tool failures
Tool result parsing and integration into reasoning flow

Planning and Coordination:

Task decomposition into manageable sub-tasks
Multi-step plan generation and execution monitoring
Dynamic plan adaptation based on intermediate results
Goal-oriented execution with success criteria validation

State Management:

Comprehensive execution state tracking and persistence
Conversation history with tool execution context
Iterative reasoning state with thought progression
Error state management and recovery mechanisms

Agent Capabilities:

Advanced Reasoning:

Multi-step logical reasoning with tool integration
Complex problem decomposition and solution synthesis
Iterative refinement of solutions based on tool feedback
Meta-reasoning about tool selection and execution strategies

Tool-Based Problem Solving:

Dynamic tool selection based on problem requirements
Parallel and sequential tool execution patterns
Tool result integration and synthesis
Error handling and alternative tool strategies

Research and Analysis:

Multi-source information gathering and synthesis
Fact verification and cross-referencing
Evidence-based reasoning and conclusion formation
Structured report generation with citations

Interactive Planning:

Real-time plan generation and adaptation
User feedback integration into reasoning loops
Progress monitoring and milestone tracking
Dynamic goal adjustment based on execution results

Examples

Basic ReactAgent with mathematical tools:

from haive.agents.react import ReactAgent
from haive.core.engine.aug_llm import AugLLMConfig
from langchain_core.tools import tool

@tool
def calculator(expression: str) -> str:
    """Calculate mathematical expressions."""
    try:
        result = eval(expression)
        return f"Result: {result}"
    except Exception as e:
        return f"Error: {e}"

@tool
def plot_generator(data: str) -> str:
    """Generate statistical plots from data."""
    return f"Generated plot for data: {data}"

# Create ReactAgent with mathematical capabilities
math_agent = ReactAgent(
    name="math_assistant",
    engine=AugLLMConfig(
        tools=[calculator, plot_generator],
        temperature=0.3,  # Lower for consistent reasoning
        system_message="You are a mathematical reasoning assistant."
    ),
    max_iterations=5
)

# Execute complex mathematical task
result = await math_agent.arun(
    "Calculate the compound interest on $10,000 at 5% annually for 3 years, "
    "then create a visualization showing the growth"
)
# Agent will:
# 1. Reason about compound interest formula
# 2. Use calculator tool for computation
# 3. Generate visualization with plot_generator
# 4. Provide comprehensive analysis

Research agent with web search and analysis tools:

from haive.agents.react import ReactAgent, create_research_agent
from langchain_core.tools import tool
import requests

@tool
def web_search(query: str) -> str:
    """Search the web for current information."""
    # Implementation would use real search API
    return f"Search results for: {query}"

@tool
def fact_checker(claim: str) -> str:
    """Verify facts using reliable sources."""
    # Implementation would check against fact databases
    return f"Fact check result for: {claim}"

@tool
def citation_formatter(source: str, format_type: str = "APA") -> str:
    """Format citations in academic style."""
    return f"Formatted citation ({format_type}): {source}"

# Create research agent using factory function
researcher = create_research_agent(
    name="academic_researcher",
    tools=[web_search, fact_checker, citation_formatter],
    max_iterations=8,
    enable_reflection=True
)

# Execute research task
result = await researcher.arun(
    "Research the latest developments in quantum computing and provide "
    "a comprehensive analysis with verified facts and proper citations"
)
# Agent will:
# 1. Break down research into subtopics
# 2. Search for current information on each topic
# 3. Fact-check important claims
# 4. Synthesize findings into coherent analysis
# 5. Add proper academic citations

ReactAgent with structured output for data analysis:

from haive.agents.react import ReactAgent
from haive.core.engine.aug_llm import AugLLMConfig
from pydantic import BaseModel, Field
from typing import List, Dict
from langchain_core.tools import tool

# Define structured output format
class DataAnalysisResult(BaseModel):
    summary: str = Field(description="Executive summary of analysis")
    key_findings: List[str] = Field(description="Main insights discovered")
    methodology: str = Field(description="Analysis approach used")
    data_quality: str = Field(description="Assessment of data quality")
    recommendations: List[str] = Field(description="Actionable recommendations")
    visualizations: List[str] = Field(description="Charts and graphs created")
    confidence_score: float = Field(ge=0.0, le=1.0, description="Confidence in analysis")

@tool
def data_loader(source: str) -> str:
    """Load data from various sources."""
    return f"Loaded data from {source}"

@tool
def statistical_analyzer(data: str, method: str) -> str:
    """Perform statistical analysis on data."""
    return f"Analysis using {method}: {data}"

@tool
def visualization_creator(data: str, chart_type: str) -> str:
    """Create data visualizations."""
    return f"Created {chart_type} chart for: {data}"

# Create data analysis agent with structured output
analyst = ReactAgent(
    name="data_analyst",
    engine=AugLLMConfig(
        tools=[data_loader, statistical_analyzer, visualization_creator],
        structured_output_model=DataAnalysisResult,
        temperature=0.2,  # Very low for analytical consistency
        system_message="You are an expert data analyst who provides thorough, evidence-based insights."
    ),
    max_iterations=10
)

# Execute comprehensive data analysis
analysis = await analyst.arun({
    "task": "Analyze customer satisfaction survey data",
    "data_source": "customer_survey_2024.csv",
    "requirements": ["identify trends", "segment analysis", "predictive insights"]
})

# Access structured results
print(f"Summary: {analysis.summary}")
print(f"Key Findings: {analysis.key_findings}")
print(f"Confidence: {analysis.confidence_score}")

Multi-agent workflow with ReactAgent coordination:

from haive.agents.react import ReactAgent
from haive.agents.simple import SimpleAgent
from haive.agents.multi import MultiAgent
from haive.core.engine.aug_llm import AugLLMConfig

# Create specialized agents for different aspects
planning_agent = ReactAgent(
    name="planner",
    engine=AugLLMConfig(
        tools=[task_decomposer, resource_planner],
        system_message="You are a strategic planner who breaks down complex projects."
    ),
    max_iterations=6
)

execution_agent = ReactAgent(
    name="executor",
    engine=AugLLMConfig(
        tools=[code_generator, tester, deployer],
        system_message="You are a technical executor who implements plans."
    ),
    max_iterations=8
)

review_agent = SimpleAgent(
    name="reviewer",
    engine=AugLLMConfig(
        system_message="You are a quality reviewer who ensures excellence."
    )
)

# Compose into project workflow
project_team = MultiAgent(
    name="software_project",
    agents=[planning_agent, execution_agent, review_agent],
    execution_mode="sequential"
)

# Execute complex project
result = await project_team.arun(
    "Build a web application for inventory management with real-time updates"
)

ReactAgent as tool for hierarchical reasoning:

from haive.agents.react import ReactAgent
from haive.core.engine.aug_llm import AugLLMConfig

# Create specialized ReactAgents
math_expert = ReactAgent(
    name="mathematician",
    engine=AugLLMConfig(
        tools=[calculator, equation_solver, graph_plotter],
        system_message="You are a mathematics expert specializing in computational problems."
    )
)

research_expert = ReactAgent(
    name="researcher",
    engine=AugLLMConfig(
        tools=[web_search, database_query, citation_tool],
        system_message="You are a research expert who gathers and verifies information."
    )
)

# Convert ReactAgents to tools
math_tool = math_expert.as_tool(
    name="mathematical_reasoning",
    description="Solve complex mathematical problems with step-by-step reasoning"
)

research_tool = research_expert.as_tool(
    name="information_research",
    description="Research and verify information using multiple sources"
)

# Use in meta-coordinator agent
coordinator = ReactAgent(
    name="project_coordinator",
    engine=AugLLMConfig(
        tools=[math_tool, research_tool],
        system_message="You coordinate expert agents to solve complex problems."
    ),
    max_iterations=15
)

# Coordinator uses other ReactAgents as reasoning tools
result = await coordinator.arun(
    "Research the mathematical foundations of machine learning and provide "
    "detailed analysis with calculations and verified sources"
)

Performance Characteristics:

Reasoning Performance:

Simple reasoning tasks: 500ms-2s depending on tool complexity
Multi-step reasoning: 2-10s for iterative problems
Tool execution overhead: 50-200ms per tool call
State management: <20ms per reasoning iteration

Scalability Metrics:

Maximum iterations: Configurable up to 50+ steps
Concurrent tool execution: 10+ parallel tool calls
Memory efficiency: Optimized state serialization
Tool management: 100+ tools per agent supported

Error Recovery:

Tool failure recovery: Automatic fallback strategies
Reasoning loop termination: Intelligent stopping criteria
State corruption recovery: Checkpoint and rollback mechanisms
Performance degradation handling: Adaptive iteration limits

Integration Patterns:

Standalone Reasoning:

Complex problem-solving applications
Research and analysis systems
Decision support tools
Interactive consultation systems

Tool Ecosystem Integration:

API service orchestration
External system coordination
Data processing pipelines
Workflow automation engines

Multi-Agent Orchestration:

Specialized expert agent coordination
Hierarchical reasoning systems
Collaborative problem-solving teams
Complex workflow management

Advanced Features:

Reflection and Self-Correction:

Automatic result validation and improvement
Meta-reasoning about reasoning quality
Alternative strategy generation
Learning from execution patterns

Dynamic Tool Management:

Runtime tool addition and removal
Tool capability discovery and matching
Tool performance monitoring and optimization
Tool composition and chaining strategies

Adaptive Reasoning:

Dynamic iteration limit adjustment
Strategy switching based on progress
Resource-aware execution planning
Performance-based optimization

Best Practices:

Tool Design:

Create focused, single-purpose tools
Implement proper error handling in tools
Provide clear, descriptive tool documentation
Design tools for composability and reuse

Reasoning Optimization:

Set appropriate iteration limits for task complexity
Use structured output for complex analysis tasks
Implement proper stopping criteria
Monitor and optimize tool execution performance

Agent Configuration:

Tune temperature based on reasoning vs creativity needs
Provide clear, specific system messages
Configure appropriate tool sets for problem domains
Enable reflection for high-stakes reasoning tasks

Factory Functions:

create_react_agent():

Convenient factory for common ReactAgent configurations
Built-in tool integration and validation
Performance optimization defaults
Enhanced debugging and observability

create_research_agent():

Specialized factory for research-oriented agents
Pre-configured for information gathering and analysis
Built-in fact-checking and citation capabilities
Research workflow optimization

Version History:

v3.0 (Current):

Enhanced reasoning loops with reflection capabilities
Improved tool management and error handling
Structured output integration with validation
Performance optimizations and debugging tools

v2.0:

Multi-step reasoning improvements
Enhanced tool integration patterns
State management and persistence enhancements

v1.0:

Initial ReAct pattern implementation
Basic tool integration and reasoning loops
Foundation reasoning agent patterns

agents.react¶

Submodules¶