🤖 mini-agent

A lightweight, modular AI agent framework with pluggable tools, multi-LLM support, and a FastAPI server.

---

Table of Contents

• Features
• Architecture
• Installation
• Quick start
• Usage
• Configuration
• Roadmap
• Contributing
• License

---

Features

• 🧠 Multi-LLM backends: OpenAI, Google Gemini
• 🔧 Pluggable tool system (search, calculator, file reader, code exec)
• 💾 Conversation memory with configurable window
• ⚡ FastAPI server with streaming endpoints
• 🐚 Typer-based CLI
• 🐳 Dockerfile + docker-compose
• ✅ Type hints throughout
• 📚 Examples & docs

Architecture

user ──▶ Agent ──▶ LLMClient ──▶ {OpenAI, Gemini}
             │
             └──▶ ToolRegistry ──▶ {search, calc, file, code_exec}

Installation

Using pip:

pip install -e .

Using Docker:

docker build -t mini-agent . && docker run --rm -e OPENAI_API_KEY=$OPENAI_API_KEY mini-agent

Quick start

from mini_agent import Agent

agent = Agent(model="gpt-4o-mini")
print(agent.run("What is the capital of Vietnam?"))

Usage

Basic chat

from mini_agent import Agent
agent = Agent()
print(agent.run("hi"))

With tools

from mini_agent import Agent
from mini_agent.tools import SearchTool, CalculatorTool
agent = Agent(tools=[SearchTool(), CalculatorTool()])
print(agent.run("13.4 * 8 then search wikipedia for the result"))

Run as API

uvicorn mini_agent.server.app:app --reload

Configuration

Variable	Default	Description
OPENAI_API_KEY	-	OpenAI API key
GEMINI_API_KEY	-	Gemini API key
MINI_AGENT_MODEL	gpt-4o-mini	Default LLM model
MINI_AGENT_MAX_STEPS	10	Max tool-use iterations

Roadmap

• Core agent loop
• OpenAI + Gemini backends
• Search, calculator, file tools
• CLI
• FastAPI server
• Multi-agent orchestration
• Streaming tokens over websocket
• Plugin marketplace

Contributing

PRs welcome. Please open an issue first to discuss any non-trivial change. Run ruff check . and pytest before submitting.

License

MIT — see LICENSE.

---

Made with care in Hanoi. 🌱