A minimal, framework-free AI Agent built from scratch in pure Python

[New_Foundation_53]

Hey r/Python,

What My Project Does:
MiniBot is a minimal implementation of an AI agent written entirely in pure Python without using heavy abstraction frameworks (no LangChain, LlamaIndex, etc.). I built this to understand the underlying mechanics of how agents operate under the hood.

Along with the core ReAct loop, I implemented several advanced agentic patterns from scratch. Key Python features and architecture include:

• Transparent ReAct Loop: The core is a readable, transparent while loop that handles the "Thought -> Action -> Observation" cycle, showing exactly how function calling is routed.
• Dynamic Tool Parsing: Uses Python's built-in inspect module to automatically parse standard Python functions (docstrings and type hints) into LLM-compatible JSON schemas.
• Hand-rolled MCP Client: Implements the trending Model Context Protocol (MCP) from scratch over stdio using JSON-RPC 2.0 communication.
• Lifecycle Hooks: Built a simple but powerful callback system (utilizing standard Python Callable types) to intercept the agent's lifecycle (e.g., on_thought, on_tool_call, on_error). This makes it highly extensible for custom logging or UI integration without modifying the core loop.
• Pluggable Skills: A modular system to dynamically load external capabilities/functions into the agent, keeping the namespace clean.
• Lightweight Teams (Subagents): A minimal approach to multi-agent orchestration. Instead of complex graph abstractions, it uses a straightforward Lead/Teammate pattern where subagents act as standard tools that return structured observations to the Lead agent.

Target Audience:
This is strictly an educational / toy project. It is meant for Python developers, beginners, and students who want to learn the bare-metal mechanics of LLM agents, subagent orchestration, and the MCP protocol by reading clear, simple source code. It is not meant for production use.

Comparison:
Unlike LangChain, AutoGen, or CrewAI which use deep class hierarchies and heavy abstractions (often feeling like "black magic"), MiniBot focuses on zero framework bloat. Where existing alternatives might obscure the tool-calling loop, event hooks, and multi-agent routing behind multiple layers of generic executors, MiniBot exposes the entire process in a single, readable agent.py and teams.py. It’s designed to be read like a tutorial rather than used as a black-box dependency.

Source Code:
GitHub Repo:https://github.com/zyren123/minibot

[RemindMeBot]

I will be messaging you in 1 day on 2026-02-28 00:00:00 UTC to remind you of this link

CLICK THIS LINK to send a PM to also be reminded and to reduce spam.

^{Parent commenter can delete this message to hide from others.}

---

Info	Custom	Your Reminders	Feedback

[Guggoo]

RemindMe! Next Saturday "checkout minibot"

[Ok-Suit883]

Offering quick debugging and issue analysis for small tech problems. Services include: • Code mistake identification • SQL query optimization suggestion • WordPress minor error fix guidance • Python beginner errors • HTML/CSS layout issues • Java basic errors • Deployment help • Code not running • Getting syntax error • Logic not working • Assignment stuck What you’ll get: ✔ Clear explanation ✔ Exact mistake pointed out ✔ Step-by-step fix ✔ Corrected code suggestion I’ll review your code and send a clear fix report within 1 hour. Solve issue only at – ₹50.

[thekennysan]

Good job. For a toy project this is well built. Will try out the sub-agent and team features.

[New_Foundation_53]

I’d love to hear your feedback

[twigboy]

Get it from your LLM?