🤖 Agentic AI Workspace

An experimental repository for building, exploring, and comparing AI Agent architectures and frameworks. This project focuses on understanding core agentic patterns—such as the ReAct (Reasoning + Acting) framework from first principles—as well as experimenting with modern agent libraries (Smolagents, LlamaIndex, LangChain) and multi-agent orchestration.

---

🌟 Highlights & Key Concepts

• ReAct Agent from Scratch: Full custom implementation of the Thought-Action-Observation loop using raw JSON structured output and OpenRouter without relying on heavy frameworks.
• Custom Tooling System: A lightweight function decorator (@tool) and wrapper class (Tool) that dynamically inspects signatures and docstrings.
• Hugging Face Smolagents Integration:
  • CodeAgent: Code-execution agent with custom @tool functions and class-based Tool subclasses.
  • RAG Agent: Retrieval-Augmented Generation using LangChain's BM25Retriever and RecursiveCharacterTextSplitter.
  • Multi-Agent Orchestration: Hierarchical manager agent delegating tasks to sub-agents (web_search_agent and rag_agent).
  • Agent Security: Python code execution sandbox control and import whitelisting.
• LlamaIndex Core: Experiments with open-source LLMs (e.g., Qwen2.5-Coder) via HuggingFaceInferenceAPI.
• FastAPI API Backend: Production-ready REST server featuring Bearer token authentication and Role-Based Access Control (RBAC).

---

📁 Repository Structure

agentic-ai/
├── src/
│ ├── core/ # Core utilities and custom tooling primitives
│ │ ├── config.py # Environment configuration (Pydantic Settings)
│ │ ├── tool.py # Custom Tool class encapsulation
│ │ └── decorator.py # @tool decorator for dynamic function inspection
│ ├── react_agent/ # ReAct pattern implementation from scratch
│ │ └── react_agent.py # Custom Thought-Action-Observation loop
│ ├── smolagents_core/ # Experiments with Hugging Face smolagents
│ │ ├── code_agent.py # CodeAgent with custom tools
│ │ ├── rag_agent.py # BM25-based Retrieval Agent
│ │ ├── multi-agent.py # Manager-Worker hierarchical multi-agent system
│ │ └── agent_security.py # Security settings & import restrictions
│ ├── llamaindex_core/ # LlamaIndex LLM integration
│ │ └── agent.py # Hugging Face Inference API agent setup
│ ├── voice_agent/ # Voice agent workspace (experimental)
│ │ └── agent.py # Placeholder for speech interaction
│ └── main.py # FastAPI app with Bearer Auth & RBAC
├── .env.example # Environment configuration template
├── makefile # Useful CLI shortcuts
├── pyproject.toml # Dependencies and project metadata
└── README.md # Project documentation

---

🧩 Module Breakdown

1. Custom ReAct Agent (src/react_agent/react_agent.py)

Implements the core Reasoning + Acting loop from the ground up:

1. Prompting: Supplies a system prompt defining available tools and strictly enforcing raw JSON outputs.
2. Loop Execution:
   • Parses LLM output into thought, action, or final_answer.
   • Executes registered tools dynamically from TOOL_REGISTRY.
   • Appends observations back to message history for multi-step reasoning.

2. Custom Tooling Primitive (src/core/)

• tool.py: Encapsulates tool metadata (name, description, arguments, outputs) and makes tool instances callable.
• decorator.py: A @tool decorator utilizing Python's inspect module to automatically generate tool specifications from docstrings and parameter type hints.

3. Smolagents Ecosystem (src/smolagents_core/)

• Custom Tools & CodeAgent (code_agent.py): Defines custom tools (e.g. menu recommenders, Gotham catering finders, theme generators) executed by a CodeAgent.
• RAG Retrieval Agent (rag_agent.py): Indexes structured knowledge into BM25Retriever documents and provides a semantic retrieval tool to a dedicated RAG agent.
• Multi-Agent Orchestration (multi-agent.py): Implements a manager agent that delegates sub-tasks to a web_search_agent and a rag_agent.
• Agent Security (agent_security.py): Restricts Python environment execution using additional_authorized_imports and use_e2b_executor.

4. LlamaIndex & Open-Source LLMs (src/llamaindex_core/)

Interactions with open models (such as Qwen/Qwen2.5-Coder-32B-Instruct) hosted on Hugging Face using HuggingFaceInferenceAPI.

5. API Backend (src/main.py)

FastAPI application with dependency-injection based authentication (HTTPBearer) and authorization (require_role, require_permission).

---

🛠️ Stack & Dependencies

• Python: >= 3.13
• Package Management: uv
• Frameworks & Libraries:
  • smolagents
  • langchain, langchain-community, langchain-core
  • llama-index-llms-huggingface-api, llama-index-embeddings-huggingface
  • fastapi, uvicorn, pydantic, pydantic-settings
  • rank-bm25
  • openrouter, transformers, torch

---

🚀 Getting Started

1. Prerequisites

Install uv (recommended) or use standard Python 3.13+.

# Clone the repository
git clone https://github.com/your-username/agentic-ai.git
cd agentic-ai
# Create virtual environment and install dependencies
uv sync

2. Environment Setup

Create a .env file in the project root:

OPEN_ROUTER_API_KEY=your_openrouter_api_key_hereHF_TOKEN=your_huggingface_token_here

---

💻 Usage & Running Examples

Run Custom ReAct Agent

uv run python -m src.react_agent.react_agent

Run Smolagents Examples

# Single CodeAgent with Custom Tools
uv run python -m src.smolagents_core.code_agent
# Hierarchical Multi-Agent System
uv run python -m src.smolagents_core.multi_agent
# Security-Constrained Agent
uv run python -m src.smolagents_core.agent_security

Run LlamaIndex Core Agent

uv run python -m src.llamaindex_core.agent

Run FastAPI Server

# Using Makefile
make run
# Or directly with Uvicorn
uv run uvicorn main:app --reload --app-dir src --host 127.0.0.1 --port 8081

Once running, view the interactive API docs at http://127.0.0.1:8081/docs.

---

🤝 Contributing

Contributions, feedback, and new agent experiment ideas are welcome! Feel free to open an issue or submit a pull request.