Mini Agent Framework

Mini Agent Framework

A small, reusable, single-agent framework built from scratch in Python. It uses a bounded ReAct execution loop and does **not** depend on an agent framework or orchestration framework. It includes provider adapters for OpenAI, Google Gemini, Anthropic Claude, and xAI Grok using their official or documented compatible SDK interfaces.

Implemented architecture

1. Agent Core & LLM Interface - reusable Agent configuration, an abstract LLMProvider, and adapters for OpenAI, Gemini, Anthropic, and xAI.
2. Input & Output Gateway - normalizes text, message lists, typed AgentRequest values, and structured dictionaries; returns a consistent AgentResult.
3. ReAct Runtime / Execution Loop - reason/decide, tool action, observation, context update, repeat/final response, with bounded turns, tool calls, LLM/tool retries, time, cumulative tokens, and resumable checkpoints.
4. Tool System - registry, metadata, JSON-style schemas, authorization, argument validation, execution, and normalized results/errors.
5. Memory & Context - conversation and tool-result history through a replaceable Memory interface and an in-memory implementation.
6. Guardrails & Observability - input/output validation, execution limits, tool restrictions, trace IDs, and structured lifecycle events.

The primary five demonstrated agent capabilities are provider-neutral LLM access, normalized interaction, ReAct execution, controlled tool use, and contextual memory. Guardrails and observability are cross-cutting controls applied to those capabilities.

Requirements

• Python 3.11+
• Git
• An API key for at least one supported provider

Clone and set up the project

Clone the public GitHub repository and enter the project directory. Replace the placeholder with the repository URL created for this project:

git clone 
cd mini-agent-framework

For example, after publishing the repository under a GitHub account: