Problem Addressed

Micro-Agent

Research Date: 2026-02-20 Source URL: https://github.com/fdueblab/Micro-Agent GitHub Repository: https://github.com/fdueblab/Micro-Agent Version at Research: v1.0.0 (from README badge; no formal releases published) License: MIT

Overview

Micro-Agent is a flexible, extensible Python agent framework designed to provide intelligent agent capabilities as a callable service layer for upstream applications. The "Micro" naming mirrors microservices architecture: lightweight, modular components that expose a standardized async streaming interface. It implements the ReAct (Reasoning + Acting) pattern over an MCP tool ecosystem, with an integrated shell environment and web-based execution visualization.

Problem Addressed

Key Statistics

Key Features

ReAct Agent Architecture

• BaseAgent (Pydantic BaseModel) defines the step-based execution loop with state machine (IDLE, RUNNING, FINISHED, ERROR)
• ReActAgent extends BaseAgent with abstract think() and act() methods; each step returns a Record dict containing thought, action, action_result, and token_usage
• max_steps configurable (default 10 for base ReAct, 40 for MCPAgent); duplicate-response detection via duplicate_threshold
• MCPAgent extends ToolCallAgent and manages tool schema refresh every N steps (_refresh_tools_interval = 5)

MCP Protocol Integration

• Connects to multiple MCP servers simultaneously via both SSE (HTTP/SSE for remote) and stdio (subprocess for local) transports
• Built-in MCP server (app/mcp/server.py) exposes: bash, cmd (Windows), terminate, file_saver, json_saver
• Additional built-in servers: aml_server, deepseek_server, mysql_server, time_server
• config.json declaratively lists external MCP server connections; auto-loaded at runtime by MCPRunner
• Tool list refreshed dynamically during agent runs to detect schema changes mid-task

LLM Abstraction Layer

• Uses OpenAI-compatible API via AsyncOpenAI; supports any OpenAI-compatible endpoint including Claude models
• Explicitly supports reasoning models (o1, o3-mini) and multimodal models (gpt-4o, claude-3-* variants) with separate handling
• TokenCounter uses tiktoken for precise per-message token counting including image token estimation (low-detail: 85 tokens, high-detail tiles: 170 tokens each)
• Retry logic via tenacity with exponential backoff for APIError, RateLimitError
• Config loaded from TOML (config/config.toml) with per-model override support; singleton thread-safe Config class

Execution Visualization

• Each agent run saves two artifacts to visualization/: {task_name}_record.json (structured execution log) and {task_name}.html (interactive HTML report)
• HTML report renders thought/action/result sequence for post-run inspection
• Web interface (app.py) on port 8010 using Flask + Flask-SocketIO + flask-restx

Deployment

• Docker image based on python:3.12-slim with SSH server exposed on port 22 (agent shell execution isolation)
• Ports: 8010 (Web UI), 22 (SSH), 8000 (docs server)
• docker-compose.yml provided for single-command startup
• meta_app.py and run_meta_app.py provide a meta-agent mode for orchestrating multiple sub-agents

Technical Architecture

Upstream Application
        |
        v
  run_agent(task_name, prompt)  [main.py async entry point]
        |
        v
    MCPRunner
    - add_server() for each config.json entry + built-in server
        |
        v
    MCPAgent (ToolCallAgent -> ReActAgent -> BaseAgent)
    - state: IDLE -> RUNNING -> FINISHED/ERROR
    - max_steps: 40
    - loop: think() -> act() -> record step -> check duplicate/terminate
        |
     think()                    act()
    - LLM.ask() with tools      - Execute MCP tool call
    - Returns: should_act,      - Returns: tool result string
      thought, action,
      token_usage
        |
        v
    MCP Tool Ecosystem
    - stdio: local subprocess servers (built-in: bash, file_saver, json_saver, terminate)
    - SSE: remote HTTP servers (configured in config.json)
    - Tool schema refreshed every 5 steps
        |
        v
    Record Persistence
    - JSON execution log -> visualization/
    - HTML report generated from JSON

The app/ module hierarchy:

app/
  agent/         # BaseAgent, ReActAgent, ToolCallAgent, MCPAgent, MetaApp agent
  llm.py         # AsyncOpenAI wrapper with TokenCounter and retry logic
  mcp/           # FastMCP-based built-in servers (bash, file tools, mysql, AML, time)
  prompt/        # System and next-step prompt templates for MCP agent
  schema.py      # Pydantic models: Message, Memory, Record, AgentState, TokenUsage
  config.py      # Singleton TOML config loader with per-model LLM settings
  tool/          # BaseTool + concrete tools: Bash, Cmd, Terminal, FileSaver, JsonSaver
  utils/         # Visualization HTML generator, record serializer

Installation & Usage

# Clone repository
git clone https://github.com/fdueblab/Micro-Agent
cd Micro-Agent

# Docker (recommended for shell isolation)
cp .env.example .env
cp config/config.example.toml config/config.toml
# Edit config.toml: set LLM model, base_url, api_key
docker-compose up -d
docker-compose exec micro_agent bash
python main.py

# Local (Python 3.12 via conda)
conda create -n micro-agent python=3.12
conda activate micro-agent
pip install -r requirements.txt
python main.py        # CLI agent run
python app.py         # Web UI on http://localhost:8010

Configuring external MCP servers in config.json:

{
  "servers": [
    {
      "connection_type": "sse",
      "server_url": "http://your-mcp-server.com/sse",
      "server_id": "remote_tools"
    },
    {
      "connection_type": "stdio",
      "command": "python",
      "args": ["-m", "your_module.mcp_server"],
      "server_id": "local_tools"
    }
  ]
}

Invoking the agent programmatically:

import asyncio
from main import run_agent

# task_name used for output filenames; prompt defines agent role and task
asyncio.run(run_agent("code_analysis", """
You are a code analyst. Examine the project structure, identify main modules,
analyze dependencies, and generate a structured report.
"""))
# Output: visualization/code_analysis_record.json
#         visualization/code_analysis.html

Relevance to Claude Code Development

Applications

• Demonstrates a clean separation pattern between agent infrastructure and task-specific prompting: the run_agent(task_name, prompt) contract is directly applicable to how Claude Code could expose agent capabilities to orchestrators
• The MCPAgent's multi-server connection management (simultaneous stdio + SSE) shows how to dynamically aggregate tools from heterogeneous MCP sources at runtime
• Token budget enforcement via TokenLimitExceeded exception prevents runaway API costs in long-running autonomous tasks

Patterns Worth Adopting

• TOML-based LLM config with per-model overrides enables switching between Claude models (opus, sonnet, haiku) per agent role without code changes
• Step-level Record persistence (thought + action + action result + token usage) provides full audit trail for debugging agent failures
• Tool schema refresh every N steps compensates for dynamic MCP server state changes during long runs
• Duplicate-response detection (duplicate_threshold) prevents infinite loops when an agent repeatedly produces the same action

Integration Opportunities

• The built-in MCP server (FastMCP wrapping Bash, FileSaver, JsonSaver) can be imported directly to extend Claude Code skill agents with shell execution capabilities
• The HTML visualization generator (app/utils/visualize_record.py) could be adapted for Claude Code skill audit reports
• MCPRunner multi-server aggregation pattern is directly applicable to Claude Code's MCP ecosystem management, particularly for routing tool calls across local and remote servers

References

• fdueblab/Micro-Agent GitHub Repository (accessed 2026-02-20)
• README.md - Micro-Agent (accessed 2026-02-20)
• app/agent/react.py - ReActAgent implementation (accessed 2026-02-20)
• app/agent/mcp.py - MCPAgent implementation (accessed 2026-02-20)
• app/llm.py - LLM wrapper with TokenCounter (accessed 2026-02-20)
• app/mcp/server.py - Built-in MCP server (accessed 2026-02-20)
• requirements.txt (accessed 2026-02-20)
• GitHub API - repos/fdueblab/Micro-Agent (accessed 2026-02-20)

Freshness Tracking