ReActFlow

A lightweight, observable ReAct Agent framework

中文文档 | English

Features • Installation • Quick Start • Documentation • Contributing

Features

• 🚀 5-minute setup - Get started with minimal code
• 🔍 Fully observable - Track every thought, action, and observation
• 💰 Cost transparent - Real-time token usage and cost tracking
• 🛠 Easy customization - Define tools with simple decorators
• 🔄 Loop detection - Automatic detection of stuck agents
• 📦 Zero dependencies core - Minimal dependencies for maximum flexibility

Installation

pip install reactflow

Quick Start

Basic Usage

from reactflow import Agent, Tool

# Define a custom tool
@Tool.define
def search(query: str) -> str:
    """Search for information"""
    return f"Results for: {query}"

# Create an agent
agent = Agent(tools=[search])

# Run a task
result = agent.run("What is the capital of France?")
print(result.answer)

CLI Usage

# Run a single task
reactflow run "Calculate 25 * 17"

# Start interactive mode
reactflow interactive

# Export trajectory
reactflow run "What is Python?" --export trajectory.json

Built-in Tools

ReActFlow comes with several built-in tools:

Custom Tools

Create custom tools easily:

from reactflow import Tool

@Tool.define
def my_tool(query: str, count: int = 5) -> str:
    """
    My custom tool description.

    Args:
        query: The search query
        count: Number of results

    Returns:
        The result string
    """
    return f"Found {count} results for '{query}'"

# Use it
agent = Agent(tools=[my_tool])

Tracking Execution

Every execution generates a complete trajectory:

result = agent.run("What is 2+2?")

# Get the trajectory
trajectory = agent.get_trajectory()

# Export as Markdown
trajectory.export("my_trajectory.md", format="markdown")

# Or as JSON
trajectory.export("my_trajectory.json", format="json")

Configuration

agent = Agent(
    tools=[search, calculator],
    model="gpt-4",           # LLM model
    max_steps=10,            # Maximum reasoning steps
    debug=True,              # Enable debug output
    temperature=0.7,         # LLM temperature
)

Architecture

ReActFlow Architecture
│
├── Agent              # Main interface
│   ├── Engine         # ReAct execution loop
│   ├── Tools          # Tool registry and execution
│   ├── State          # Execution state tracking
│   └── Memory         # Conversation memory
│
└── CLI                # Command-line interface

Why ReActFlow?

Academic Reference

This framework implements the ReAct (Reasoning + Acting) paradigm from the following paper:

ReAct: Synergizing Reasoning and Acting in Language Models

Shunyu Yao, Jeffrey Zhao, Dian Yu, Nan Du, Izhak Shafran, Karthik R. Narasimhan, Yuan Cao

ICLR 2023

Paper: https://arxiv.org/abs/2210.03629

@inproceedings{yao2023react,
  title={ReAct: Synergizing Reasoning and Acting in Language Models},
  author={Yao, Shunyu and Zhao, Jeffrey and Yu, Dian and Du, Nan and Shafran, Izhak and Narasimhan, Karthik R and Cao, Yuan},
  booktitle={International Conference on Learning Representations (ICLR)},
  year={2023}
}

License

This project is licensed under the MIT License.

MIT License

Copyright (c) 2024 AI Agent Research Team

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Made with ❤️ by AI Agent Research Team