Mini Agent Platform

A multi-tenant backend platform for managing AI agents, tools, and their execution history. Built with FastAPI, SQLAlchemy, and MySQL.

Table of Contents

• Overview
• Features
• Quick Setup
• Project Structure
• API Documentation
• API Examples
• Authentication
• Architecture Overview

Overview

The Mini Agent Platform is a RESTful API that enables you to:

• Manage Tools: Create, read, update, and delete tools that agents can use
• Manage Agents: Create agents with specific roles and associate them with tools
• Execute Agents: Run agents with tasks and receive mock LLM responses
• Track History: View execution history with full prompt and response details
• Multi-Tenancy: Complete tenant isolation using API key-based authentication

Features

• Multi-Tenant Architecture: Complete data isolation per tenant
• RESTful API: FastAPI with automatic OpenAPI documentation
• Database Migrations: Alembic for version-controlled schema changes
• Comprehensive Testing: Unit tests with isolated test database
• Mock LLM: Deterministic mock responses for development and testing
• Type Safety: Pydantic schemas for request/response validation
• Multiple LLM Models: Support for GPT-4o and Claude Sonnet 4.5

Quick Setup

For detailed setup instructions, installation steps, and troubleshooting, see QUICK_SETUP.md.

TL;DR - Get started in 2 commands:

./setup.sh  # First time only
./start.sh  # Start the platform

The API will be available at http://localhost:8000/docs

Project Structure

mini_agent_platform/
├── app/                          # Main application package
│   ├── __init__.py
│   ├── main.py                   # FastAPI app entry point
│   ├── config.py                 # Configuration (settings, API keys)
│   ├── database.py               # Database connection & session management
│   │
│   ├── models/                   # SQLAlchemy database models
│   │   ├── __init__.py
│   │   ├── tool.py              # Tool model
│   │   ├── agent.py             # Agent model
│   │   ├── agent_tool.py        # Many-to-Many association table
│   │   └── execution.py         # Execution history model
│   │
│   ├── schemas/                  # Pydantic schemas (API validation)
│   │   ├── __init__.py
│   │   ├── tool.py              # Tool request/response schemas
│   │   ├── agent.py             # Agent request/response schemas
│   │   └── execution.py        # Execution request/response schemas
│   │
│   ├── services/                 # Business logic layer
│   │   ├── __init__.py
│   │   ├── tool_service.py     # Tool CRUD operations
│   │   ├── agent_service.py     # Agent CRUD operations
│   │   └── execution_service.py # Execution & history operations
│   │
│   ├── api/                      # API routes (HTTP endpoints)
│   │   ├── __init__.py
│   │   ├── dependencies.py      # Authentication dependency
│   │   ├── tools.py             # Tool endpoints
│   │   ├── agents.py            # Agent endpoints
│   │   └── executions.py         # Execution endpoints
│   │
│   └── llm/                      # Mock LLM adapter
│       ├── __init__.py
│       └── mock_llm.py          # Mock LLM prompt & response generation
│
├── alembic/                      # Database migrations
│   ├── env.py                   # Alembic environment configuration
│   ├── script.py.mako          # Migration script template
│   └── versions/                # Migration files
│
├── tests/                        # Unit tests
│   ├── __init__.py
│   ├── conftest.py              # Pytest fixtures & test configuration
│   ├── test_tools.py            # Tool API tests
│   ├── test_agents.py           # Agent API tests
│   ├── test_executions.py       # Execution API tests
│   └── test_models.py           # Database model tests
│
├── alembic.ini                   # Alembic configuration file
├── requirements.txt              # Python dependencies
├── README.md                     # This file
└── QUICK_SETUP.md               # Quick setup guide

API Documentation

Interactive Documentation

Once the server is running, visit:

• Swagger UI: http://localhost:8000/docs

API Endpoints Overview

Tools

• POST /tools - Create a new tool
• GET /tools - List all tools (with optional agent_name filter)
• GET /tools/{tool_id} - Get a specific tool
• PUT /tools/{tool_id} - Update a tool
• DELETE /tools/{tool_id} - Delete a tool

Agents

• POST /agents - Create a new agent (with optional tool_ids)
• GET /agents - List all agents (with optional tool_name filter)
• GET /agents/{agent_id} - Get a specific agent (with tools)
• PUT /agents/{agent_id} - Update an agent (including tools)
• DELETE /agents/{agent_id} - Delete an agent

Executions

• POST /executions/agents/{agent_id}/run - Run an agent with a task
• GET /executions - List execution history (with optional agent_id filter)
• GET /executions/{execution_id} - Get a specific execution

Authentication

All API endpoints require authentication via an API key in the request header.

Header Format

X-API-Key: <your_api_key>

Default API Keys

• Tenant 1: api_key_tenant_1
• Tenant 2: api_key_tenant_2

Example

curl -X GET "http://localhost:8000/tools" \
  -H "X-API-Key: api_key_tenant_1"

Note: In production, API keys should be stored securely (database with hashing, secrets manager, etc.). The current implementation uses a simple dictionary for demonstration purposes.

API Examples

Create a Tool

curl -X POST "http://localhost:8000/tools" \
  -H "X-API-Key: api_key_tenant_1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-search",
    "description": "Search the web for information"
  }'

Response:

{
  "id": 1,
  "tenant_id": "tenant_1",
  "name": "web-search",
  "description": "Search the web for information",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Create an Agent with Tools

curl -X POST "http://localhost:8000/agents" \
  -H "X-API-Key: api_key_tenant_1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "research-agent",
    "role": "Research Assistant",
    "description": "An agent that helps with research tasks",
    "tool_ids": [1]
  }'

Run an Agent

You can run an agent mock with either gpt-4o or claude-sonnet-4.5 model:

Using GPT-4o:

curl -X POST "http://localhost:8000/executions/agents/1/run" \
  -H "X-API-Key: api_key_tenant_1" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Summarize the Q2 financial report",
    "model": "gpt-4o"
  }'

Using Claude Sonnet 4.5:

curl -X POST "http://localhost:8000/executions/agents/1/run" \
  -H "X-API-Key: api_key_tenant_1" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Analyze market trends for Q3",
    "model": "claude-sonnet-4.5"
  }'

Response:

{
  "id": 1,
  "tenant_id": "tenant_1",
  "agent_id": 1,
  "task": "Summarize the Q2 financial report",
  "model": "gpt-4o",
  "prompt": "You are research-agent, a Research Assistant...",
  "response": "[Mock LLM Response - Model: gpt-4o]...",
  "created_at": "2024-01-15T10:35:00Z"
}

List Executions

curl -X GET "http://localhost:8000/executions?agent_id=1&skip=0&limit=10" \
  -H "X-API-Key: api_key_tenant_1"

Architecture Overview

Layer Separation

1. Models (app/models/): Database schema definitions (SQLAlchemy)
2. Schemas (app/schemas/): API request/response validation (Pydantic)
3. Services (app/services/): Business logic and data operations
4. API (app/api/): HTTP endpoints and request handling
5. LLM (app/llm/): Mock LLM adapter for agent execution

Data Flow

Client Request
    ↓
API Route (app/api/)
    ↓
Authentication (dependencies.py)
    ↓
Service Layer (app/services/)
    ↓
Database Models (app/models/)
    ↓
SQLAlchemy → MySQL Database

Multi-Tenancy

• Every table includes a tenant_id column
• All queries are automatically filtered by tenant_id
• Tenant ID is extracted from the API key via dependency injection
• Complete data isolation between tenants