| Name | react-agent-framework JSON |
| Version |
0.9.1
JSON |
| download |
| home_page | None |
| Summary | Complete AI agent framework with MCP support, environments, reasoning strategies, objectives, memory, and built-in tools |
| upload_time | 2025-10-08 21:49:49 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | MIT |
| keywords |
ai
agent
react
llm
openai
framework
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
|
# ReAct Agent Framework
> Framework for creating AI agents using the ReAct pattern (Reasoning + Acting) - **FastAPI-style API**
[](https://www.python.org/downloads/)
[](https://badge.fury.io/py/react-agent-framework)
[](https://pepy.tech/project/react-agent-framework)
[](https://github.com/marcosf63/react-agent-framework/actions/workflows/test.yml)
[](https://opensource.org/licenses/MIT)
[](https://marcosf63.github.io/react-agent-framework/)
## 🤖 What is ReAct?
ReAct (Reasoning + Acting) is an agent pattern that alternates between:
- **Thought (Reasoning)**: Reasoning about what to do
- **Action (Acting)**: Executing an action using available tools
- **Observation**: Analyzing the action result
This cycle continues until the agent has enough information to answer.
## 🚀 Features
- ✅ **FastAPI-style API** - Elegant and intuitive agent creation
- ✅ **Decorator-based tools** - Register functions as tools with `@agent.tool()`
- ✅ **Rich configuration** - Name, description, model, instructions, and more
- ✅ **Interactive CLI** - Built with Typer and Rich
- ✅ **Verbose mode** - Debug agent reasoning step-by-step
- ✅ **Clean Python API** - Minimal code, maximum functionality
- ✅ **Type hints** - Full typing support
- ✅ **Easy to extend** - Create custom tools effortlessly
## 📋 Prerequisites
- Python 3.8+
- OpenAI API key
## 🔧 Installation
### From PyPI (Recommended)
```bash
# Basic installation
pip install react-agent-framework
# With all optional dependencies
pip install react-agent-framework[all]
# With specific providers
pip install react-agent-framework[anthropic] # Claude support
pip install react-agent-framework[google] # Gemini support
# With memory backends
pip install react-agent-framework[memory-chroma] # ChromaDB
pip install react-agent-framework[memory-faiss] # FAISS
# With MCP support
pip install react-agent-framework[mcp]
```
### From source (Development)
```bash
# Clone the repository
git clone https://github.com/marcosf63/react-agent-framework.git
cd react-agent-framework
# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install in editable mode
pip install -e .
# Configure OpenAI key
cp .env.example .env
# Edit .env file and add your OPENAI_API_KEY
```
## 💻 Usage
### FastAPI-Style API (Recommended)
The framework provides a FastAPI-inspired API for creating agents:
```python
from react_agent_framework import ReactAgent
# Create agent with rich configuration
agent = ReactAgent(
name="Research Assistant",
description="An AI assistant for web research",
model="gpt-4o-mini",
instructions="You are a helpful research assistant.",
max_iterations=10
)
# Register tools using decorators (just like FastAPI routes!)
@agent.tool()
def search(query: str) -> str:
"""Search the internet for information"""
# Your search implementation
return search_results
@agent.tool()
def calculate(expression: str) -> str:
"""Perform mathematical calculations"""
result = eval(expression, {"__builtins__": {}}, {})
return f"Result: {result}"
# Run the agent
answer = agent.run("What is the capital of France?", verbose=True)
print(answer)
```
### CLI (Command Line Interface)
After installation, the `react-agent` command is available:
**Ask a single question:**
```bash
react-agent ask "What is the capital of France?"
```
**Verbose mode (shows reasoning):**
```bash
react-agent ask "What is the capital of France?" --verbose
# or
react-agent ask "What is the capital of France?" -v
```
**Interactive mode:**
```bash
react-agent interactive
# or with verbose
react-agent interactive --verbose
```
**Choose different model:**
```bash
react-agent ask "Search about AI" --model gpt-4
```
**Show version:**
```bash
react-agent version
```
**Help:**
```bash
react-agent --help
react-agent ask --help
```
## 🎯 Agent Configuration
```python
agent = ReactAgent(
name="Assistant Name", # Agent name
description="Agent description", # What the agent does
model="gpt-4o-mini", # OpenAI model
instructions="Custom instructions", # Agent system prompt
temperature=0, # Model temperature (0-1)
max_iterations=10, # Max reasoning cycles
execution_date=datetime.now(), # Execution timestamp
api_key="sk-..." # OpenAI API key (optional)
)
```
## 🛠️ Creating Custom Tools
Tools are registered using the `@agent.tool()` decorator:
```python
@agent.tool()
def my_tool(input_text: str) -> str:
"""Tool description (used by the agent)"""
# Your implementation
return result
# With custom name and description
@agent.tool(name="custom_name", description="Custom description")
def another_tool(data: str) -> str:
return processed_data
```
## 📁 Project Structure
```
react-agent-framework/
├── react_agent_framework/ # Main package
│ ├── __init__.py # Public exports
│ ├── core/ # Framework core
│ │ ├── __init__.py
│ │ └── react_agent.py # ReactAgent implementation
│ ├── cli/ # CLI interface
│ │ ├── __init__.py
│ │ └── app.py # Typer application
│ └── examples/ # Usage examples
│ ├── fastapi_style.py # FastAPI-style example
│ └── custom_tools.py # Custom tools example
├── pyproject.toml # Project configuration
├── setup.py # Package setup
├── CHANGELOG.md # Version history
├── LICENSE # MIT License
└── README.md # This file
```
## 🔍 How It Works
1. **User asks a question** → "What is the capital of France?"
2. **Agent thinks** → "I need to search for the capital of France"
3. **Agent acts** → Uses the search tool
4. **Agent observes** → Receives: "Paris is the capital of France..."
5. **Agent thinks** → "Now I have the necessary information"
6. **Agent finishes** → "The capital of France is Paris"
## 📚 Examples
### Basic Example
```python
from react_agent_framework import ReactAgent
agent = ReactAgent(name="Assistant")
@agent.tool()
def greet(name: str) -> str:
"""Greet someone"""
return f"Hello, {name}!"
answer = agent.run("Greet John")
print(answer) # "Hello, John!"
```
### Advanced Example
See [examples/fastapi_style.py](react_agent_framework/examples/fastapi_style.py) and [examples/custom_tools.py](react_agent_framework/examples/custom_tools.py) for complete examples.
## 🛠️ Development
### Install development dependencies
```bash
pip install -e ".[dev]"
```
### Run examples
```bash
# FastAPI-style example
python -m react_agent_framework.examples.fastapi_style
# Custom tools example
python -m react_agent_framework.examples.custom_tools
```
### Code quality
```bash
# Format code
black react_agent_framework/
# Check linting
ruff check react_agent_framework/
# Type checking
mypy react_agent_framework/ --ignore-missing-imports
```
## 🎯 Use Cases
- 🔍 Research and information analysis
- 🧮 Calculations and data processing
- 🤖 Intelligent virtual assistants
- 📊 Automated analysis and reports
- 🔧 Complex task automation
- 💡 Any application requiring reasoning + action
## ⚙️ API Reference
### ReactAgent
Main class for creating ReAct agents.
**Methods:**
- `tool(name=None, description=None)`: Decorator to register tools
- `run(query, verbose=False)`: Execute agent with a query
- `arun(query, verbose=False)`: Async version (future)
- `clear_history()`: Clear execution history
- `get_tools()`: Get registered tools
## 🤝 Contributing
Contributions are welcome! To contribute:
1. Fork the repository
2. Create a branch for your feature (`git checkout -b feature/MyFeature`)
3. Commit your changes (`git commit -m 'Add MyFeature'`)
4. Push to the branch (`git push origin feature/MyFeature`)
5. Open a Pull Request
### Contribution ideas
- Add new built-in tools
- Improve agent prompting
- Add support for other LLMs (Anthropic, Google, etc)
- Implement tests
- Improve documentation
- Create more examples
## 📝 License
This project is under the MIT license. See the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Inspired by the paper [ReAct: Synergizing Reasoning and Acting in Language Models](https://arxiv.org/abs/2210.03629)
- Built with [OpenAI API](https://openai.com/), [Typer](https://typer.tiangolo.com/), and [Rich](https://rich.readthedocs.io/)
- API design inspired by [FastAPI](https://fastapi.tiangolo.com/)
## 📧 Contact
Marcos - marcosf63@gmail.com
GitHub: https://github.com/marcosf63/react-agent-framework
---
**Built with ❤️ using ReAct Agent Framework**
Raw data
{
"_id": null,
"home_page": null,
"name": "react-agent-framework",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "ai, agent, react, llm, openai, framework",
"author": null,
"author_email": "Marcos <marcosf63@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b8/54/cbce8df67635c951819912d880e2cb9e24b6f944b3fd68209cf1d040f4d7/react_agent_framework-0.9.1.tar.gz",
"platform": null,
"description": "# ReAct Agent Framework\n\n> Framework for creating AI agents using the ReAct pattern (Reasoning + Acting) - **FastAPI-style API**\n\n[](https://www.python.org/downloads/)\n[](https://badge.fury.io/py/react-agent-framework)\n[](https://pepy.tech/project/react-agent-framework)\n[](https://github.com/marcosf63/react-agent-framework/actions/workflows/test.yml)\n[](https://opensource.org/licenses/MIT)\n[](https://marcosf63.github.io/react-agent-framework/)\n\n## \ud83e\udd16 What is ReAct?\n\nReAct (Reasoning + Acting) is an agent pattern that alternates between:\n- **Thought (Reasoning)**: Reasoning about what to do\n- **Action (Acting)**: Executing an action using available tools\n- **Observation**: Analyzing the action result\n\nThis cycle continues until the agent has enough information to answer.\n\n## \ud83d\ude80 Features\n\n- \u2705 **FastAPI-style API** - Elegant and intuitive agent creation\n- \u2705 **Decorator-based tools** - Register functions as tools with `@agent.tool()`\n- \u2705 **Rich configuration** - Name, description, model, instructions, and more\n- \u2705 **Interactive CLI** - Built with Typer and Rich\n- \u2705 **Verbose mode** - Debug agent reasoning step-by-step\n- \u2705 **Clean Python API** - Minimal code, maximum functionality\n- \u2705 **Type hints** - Full typing support\n- \u2705 **Easy to extend** - Create custom tools effortlessly\n\n## \ud83d\udccb Prerequisites\n\n- Python 3.8+\n- OpenAI API key\n\n## \ud83d\udd27 Installation\n\n### From PyPI (Recommended)\n\n```bash\n# Basic installation\npip install react-agent-framework\n\n# With all optional dependencies\npip install react-agent-framework[all]\n\n# With specific providers\npip install react-agent-framework[anthropic] # Claude support\npip install react-agent-framework[google] # Gemini support\n\n# With memory backends\npip install react-agent-framework[memory-chroma] # ChromaDB\npip install react-agent-framework[memory-faiss] # FAISS\n\n# With MCP support\npip install react-agent-framework[mcp]\n```\n\n### From source (Development)\n\n```bash\n# Clone the repository\ngit clone https://github.com/marcosf63/react-agent-framework.git\ncd react-agent-framework\n\n# Create and activate virtual environment\npython -m venv .venv\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\activate\n\n# Install in editable mode\npip install -e .\n\n# Configure OpenAI key\ncp .env.example .env\n# Edit .env file and add your OPENAI_API_KEY\n```\n\n## \ud83d\udcbb Usage\n\n### FastAPI-Style API (Recommended)\n\nThe framework provides a FastAPI-inspired API for creating agents:\n\n```python\nfrom react_agent_framework import ReactAgent\n\n# Create agent with rich configuration\nagent = ReactAgent(\n name=\"Research Assistant\",\n description=\"An AI assistant for web research\",\n model=\"gpt-4o-mini\",\n instructions=\"You are a helpful research assistant.\",\n max_iterations=10\n)\n\n# Register tools using decorators (just like FastAPI routes!)\n@agent.tool()\ndef search(query: str) -> str:\n \"\"\"Search the internet for information\"\"\"\n # Your search implementation\n return search_results\n\n@agent.tool()\ndef calculate(expression: str) -> str:\n \"\"\"Perform mathematical calculations\"\"\"\n result = eval(expression, {\"__builtins__\": {}}, {})\n return f\"Result: {result}\"\n\n# Run the agent\nanswer = agent.run(\"What is the capital of France?\", verbose=True)\nprint(answer)\n```\n\n### CLI (Command Line Interface)\n\nAfter installation, the `react-agent` command is available:\n\n**Ask a single question:**\n```bash\nreact-agent ask \"What is the capital of France?\"\n```\n\n**Verbose mode (shows reasoning):**\n```bash\nreact-agent ask \"What is the capital of France?\" --verbose\n# or\nreact-agent ask \"What is the capital of France?\" -v\n```\n\n**Interactive mode:**\n```bash\nreact-agent interactive\n# or with verbose\nreact-agent interactive --verbose\n```\n\n**Choose different model:**\n```bash\nreact-agent ask \"Search about AI\" --model gpt-4\n```\n\n**Show version:**\n```bash\nreact-agent version\n```\n\n**Help:**\n```bash\nreact-agent --help\nreact-agent ask --help\n```\n\n## \ud83c\udfaf Agent Configuration\n\n```python\nagent = ReactAgent(\n name=\"Assistant Name\", # Agent name\n description=\"Agent description\", # What the agent does\n model=\"gpt-4o-mini\", # OpenAI model\n instructions=\"Custom instructions\", # Agent system prompt\n temperature=0, # Model temperature (0-1)\n max_iterations=10, # Max reasoning cycles\n execution_date=datetime.now(), # Execution timestamp\n api_key=\"sk-...\" # OpenAI API key (optional)\n)\n```\n\n## \ud83d\udee0\ufe0f Creating Custom Tools\n\nTools are registered using the `@agent.tool()` decorator:\n\n```python\n@agent.tool()\ndef my_tool(input_text: str) -> str:\n \"\"\"Tool description (used by the agent)\"\"\"\n # Your implementation\n return result\n\n# With custom name and description\n@agent.tool(name=\"custom_name\", description=\"Custom description\")\ndef another_tool(data: str) -> str:\n return processed_data\n```\n\n## \ud83d\udcc1 Project Structure\n\n```\nreact-agent-framework/\n\u251c\u2500\u2500 react_agent_framework/ # Main package\n\u2502 \u251c\u2500\u2500 __init__.py # Public exports\n\u2502 \u251c\u2500\u2500 core/ # Framework core\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u2514\u2500\u2500 react_agent.py # ReactAgent implementation\n\u2502 \u251c\u2500\u2500 cli/ # CLI interface\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u2514\u2500\u2500 app.py # Typer application\n\u2502 \u2514\u2500\u2500 examples/ # Usage examples\n\u2502 \u251c\u2500\u2500 fastapi_style.py # FastAPI-style example\n\u2502 \u2514\u2500\u2500 custom_tools.py # Custom tools example\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u251c\u2500\u2500 setup.py # Package setup\n\u251c\u2500\u2500 CHANGELOG.md # Version history\n\u251c\u2500\u2500 LICENSE # MIT License\n\u2514\u2500\u2500 README.md # This file\n```\n\n## \ud83d\udd0d How It Works\n\n1. **User asks a question** \u2192 \"What is the capital of France?\"\n\n2. **Agent thinks** \u2192 \"I need to search for the capital of France\"\n\n3. **Agent acts** \u2192 Uses the search tool\n\n4. **Agent observes** \u2192 Receives: \"Paris is the capital of France...\"\n\n5. **Agent thinks** \u2192 \"Now I have the necessary information\"\n\n6. **Agent finishes** \u2192 \"The capital of France is Paris\"\n\n## \ud83d\udcda Examples\n\n### Basic Example\n\n```python\nfrom react_agent_framework import ReactAgent\n\nagent = ReactAgent(name=\"Assistant\")\n\n@agent.tool()\ndef greet(name: str) -> str:\n \"\"\"Greet someone\"\"\"\n return f\"Hello, {name}!\"\n\nanswer = agent.run(\"Greet John\")\nprint(answer) # \"Hello, John!\"\n```\n\n### Advanced Example\n\nSee [examples/fastapi_style.py](react_agent_framework/examples/fastapi_style.py) and [examples/custom_tools.py](react_agent_framework/examples/custom_tools.py) for complete examples.\n\n## \ud83d\udee0\ufe0f Development\n\n### Install development dependencies\n\n```bash\npip install -e \".[dev]\"\n```\n\n### Run examples\n\n```bash\n# FastAPI-style example\npython -m react_agent_framework.examples.fastapi_style\n\n# Custom tools example\npython -m react_agent_framework.examples.custom_tools\n```\n\n### Code quality\n\n```bash\n# Format code\nblack react_agent_framework/\n\n# Check linting\nruff check react_agent_framework/\n\n# Type checking\nmypy react_agent_framework/ --ignore-missing-imports\n```\n\n## \ud83c\udfaf Use Cases\n\n- \ud83d\udd0d Research and information analysis\n- \ud83e\uddee Calculations and data processing\n- \ud83e\udd16 Intelligent virtual assistants\n- \ud83d\udcca Automated analysis and reports\n- \ud83d\udd27 Complex task automation\n- \ud83d\udca1 Any application requiring reasoning + action\n\n## \u2699\ufe0f API Reference\n\n### ReactAgent\n\nMain class for creating ReAct agents.\n\n**Methods:**\n- `tool(name=None, description=None)`: Decorator to register tools\n- `run(query, verbose=False)`: Execute agent with a query\n- `arun(query, verbose=False)`: Async version (future)\n- `clear_history()`: Clear execution history\n- `get_tools()`: Get registered tools\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! To contribute:\n\n1. Fork the repository\n2. Create a branch for your feature (`git checkout -b feature/MyFeature`)\n3. Commit your changes (`git commit -m 'Add MyFeature'`)\n4. Push to the branch (`git push origin feature/MyFeature`)\n5. Open a Pull Request\n\n### Contribution ideas\n\n- Add new built-in tools\n- Improve agent prompting\n- Add support for other LLMs (Anthropic, Google, etc)\n- Implement tests\n- Improve documentation\n- Create more examples\n\n## \ud83d\udcdd License\n\nThis project is under the MIT license. See the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- Inspired by the paper [ReAct: Synergizing Reasoning and Acting in Language Models](https://arxiv.org/abs/2210.03629)\n- Built with [OpenAI API](https://openai.com/), [Typer](https://typer.tiangolo.com/), and [Rich](https://rich.readthedocs.io/)\n- API design inspired by [FastAPI](https://fastapi.tiangolo.com/)\n\n## \ud83d\udce7 Contact\n\nMarcos - marcosf63@gmail.com\n\nGitHub: https://github.com/marcosf63/react-agent-framework\n\n---\n\n**Built with \u2764\ufe0f using ReAct Agent Framework**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Complete AI agent framework with MCP support, environments, reasoning strategies, objectives, memory, and built-in tools",
"version": "0.9.1",
"project_urls": {
"Documentation": "https://marcosf63.github.io/react-agent-framework/",
"Homepage": "https://marcosf63.github.io/react-agent-framework/",
"Issues": "https://github.com/marcosf63/react-agent-framework/issues",
"Repository": "https://github.com/marcosf63/react-agent-framework"
},
"split_keywords": [
"ai",
" agent",
" react",
" llm",
" openai",
" framework"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a602bec31ee69aa5b5645a8e4f8414fd1b714f6be486fdf64fd4668447cb7bbe",
"md5": "238f510aa68dceaa4836d1d6a2b2711f",
"sha256": "8c2a57b375166ba2f026670849f3d14080eb2c2f47d2aa405f5b579fcdaeaae9"
},
"downloads": -1,
"filename": "react_agent_framework-0.9.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "238f510aa68dceaa4836d1d6a2b2711f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 88988,
"upload_time": "2025-10-08T21:49:48",
"upload_time_iso_8601": "2025-10-08T21:49:48.338049Z",
"url": "https://files.pythonhosted.org/packages/a6/02/bec31ee69aa5b5645a8e4f8414fd1b714f6be486fdf64fd4668447cb7bbe/react_agent_framework-0.9.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b854cbce8df67635c951819912d880e2cb9e24b6f944b3fd68209cf1d040f4d7",
"md5": "0cd27279ae0371ecb52db0e33d76410f",
"sha256": "f714c8321580b00050a27695430899462473d19221f5c4a094f1195cc02ef08e"
},
"downloads": -1,
"filename": "react_agent_framework-0.9.1.tar.gz",
"has_sig": false,
"md5_digest": "0cd27279ae0371ecb52db0e33d76410f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 69859,
"upload_time": "2025-10-08T21:49:49",
"upload_time_iso_8601": "2025-10-08T21:49:49.630348Z",
"url": "https://files.pythonhosted.org/packages/b8/54/cbce8df67635c951819912d880e2cb9e24b6f944b3fd68209cf1d040f4d7/react_agent_framework-0.9.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-08 21:49:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "marcosf63",
"github_project": "react-agent-framework",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "react-agent-framework"
}
