ReAct Planning Agent Service 🤖🧠✈️

An AI microservice that implements the ReAct (Reason + Act) framework to solve complex problems that require multiple steps. The agent dynamically creates an action plan, utilizes tools to gather information, and executes a Thought -> Action -> Observation loop until it reaches the final goal.

This project demonstrates the construction of an autonomous agent capable of moving beyond simple Q&A to execute end-to-end processes.

🧠 Core Concept: The ReAct Reasoning Loop

The ReAct framework enables an LLM to mimic human-like reasoning to solve problems. Instead of generating a final answer in one go, the agent engages in a structured "internal monologue":

1. Thought: The agent analyzes the problem and the current state, then verbalizes the next logical step in its plan.
2. Action: Based on its thought, the agent decides to use one of its tools. It formats this decision into a structured JSON object, specifying the tool and its input.
3. Observation: The agent receives the result from the tool's execution. This observation serves as new input for the next step.
4. Loop: The agent repeats the Thought -> Action -> Observation cycle, using each new observation to refine its plan and move closer to the solution.
5. Final Answer: When the agent determines it has gathered enough information, it breaks the loop and synthesizes all its findings into a final response for the user.

🚀 Engineering & MLOps Highlights

This project is a case study in orchestrating autonomous agents and leveraging a robust, reusable microservice architecture.

• Autonomous State Machine Agent: The core logic is a for loop that acts as a finite state machine, managing the ReAct cycle with a max_steps safeguard to prevent infinite loops.
• Tools with Structured JSON Inputs: The tools are designed to accept JSON inputs, allowing the agent to pass multiple parameters and execute more complex actions.
• Reasoning Loop Unit Tests: The agent's reasoning pipeline, including the multi-step success path and the safety stop condition, is validated with Pytest and pytest-mock's side_effect feature.
• Reusable Infrastructure: 90% of the API (FastAPI), containerization (Docker), and CI/CD (GitHub Actions) infrastructure was reused from previous projects, demonstrating an efficient and scalable development pattern.

🏗️ Service Architecture

graph TD
    A[User] -->|Goal| B(FastAPI Service);
    B -->|prompt| C{ReActAgent};
    subgraph "Reasoning Loop (ReAct)"
        C -->|1. Thought/Action| D[OpenAI API];
        D -->|Action JSON| C;
        C -->|2. Execute Tool| E(Tools);
        E -->|3. Observation| C;
    end
    C -->|Final Answer| D;
    D -->|Final Text| C;
    C -->|Complete Response| B;
    B -->|JSON Response| A;

Loading

🏁 Getting Started

Prerequisites

• Git, Python 3.9+, Docker Desktop

1. Running Locally (for Development)

1. Clone: `git clone https