Self‑healing MCP agent framework with adaptive orchestration and automatic retraining

Quick Start • Features • Examples • Contributing

What is this?

AgentForge is a Python framework that enables developers to build autonomous AI agents capable of self‑diagnosing failures, triggering retraining when performance degrades, and transparently reconnecting to MCP‑enabled tools. It is aimed at solo AI developers who ship MCP‑enabled servers and want to reduce manual operational overhead.

$ agentforge run --agent-id demo-agent
[AgentForge] Starting agent demo-agent
[AgentForge] Heartbeat interval set to 30.0s
[AgentForge] MCP connector bound to localhost:8000
[AgentForge] Agent ready – awaiting tasks

Features

Feature	Description
Self‑Diagnosis & Failure Detection	Continuously monitors health metrics (CPU, latency, error rate) and emits a fault event within 200 ms of anomaly detection.
Adaptive Retraining Trigger	Upon fault detection, schedules a retraining job using the latest model artifact within 1 second and persists job state for resume.
Dynamic MCP Reconnection	Detects MCP endpoint loss within 500 ms, fails over to a hot‑standby endpoint within 1 second, and replays in‑flight requests transparently.
Heartbeat Monitoring	Sends periodic heartbeats to confirm agent liveness; interval configurable via AgentConfig.
Configurable Logging	Verbosity controlled by AGENTFORGE_LOG_LEVEL environment variable (DEBUG, INFO, WARNING, ERROR).
CLI Entrypoint	Provides agentforge run, agentforge self-heal test-fault-detect, and agentforge orchestrator test-retrain-trigger commands for quick validation.
Pluggable Health Probes	Health checks can be extended without modifying core logic; each probe reports to the internal bus.
Model Version Retrieval	Queries the configured model registry to obtain the latest version before starting retraining.

Quick Start

1. Clone the repository:

   git clone https://github.com/m2ai-portfolio/AgentForge.git
   cd AgentForge

2. Install the package in editable mode (requires Python 3.11+):

   pip install -e .

3. Run the agent with a test identifier:

   agentforge run --agent-id tutorial

   Expected output similar to the example in the "What is this?" section.

Examples

Basic agent startup

$ agentforge run --agent-id demo
[AgentForge] Starting agent demo
[AgentForge] Heartbeat interval set to 30.0s
[AgentForge] MCP connector bound to localhost:8000
[AgentForge] Agent ready – awaiting tasks

Simulate a fault and verify retraining trigger

$ agentforge self-heal test-fault-detect
[SelfHealer] Fault injected: latency spike 2.5s
[SelfHealer] Fault event emitted trace-id=abc123
[Orchestrator] Retraining job scheduled for model v2.1.0
[Orchestrator] Job state persisted to checkpoint file

Test MCP reconnection with a standby endpoint

$ agentforge mcp-client test-reconnect-success
[MCPClient] Primary endpoint localhost:8000 unreachable
[MCPClient] Failover to standby localhost:8001 completed in 750ms
[MCPClient] Replayed 2 in‑flight requests
[MCPClient] Connection restored to primary endpoint

File Structure

AgentForge: Self-Healing MCP Agent Framework with Built-in Adaptive Orchestration/
  agentforge/          # Core source code
    __init__.py
    cli.py             # CLI command definitions
    core.py            # AgentCore and heartbeat logic
    self_heal.py       # Fault detection and event emission
    orchestrator.py    # Retraining workflow and job persistence
    mcp_client.py      # MCP connection handling and failover
    models.py          # Pydantic models AgentConfig & MCPToolSpec
  tests/               # Test suite
    __init__.py
    test_cli.py
    test_core.py
    test_self_heal.py
    test_mcp_client.py
  pyproject.toml       # Project metadata and dependencies
  README.md            # This file
  spec.md              # Detailed specification (optional)

Tech Stack

Technology	Purpose
Python 3.11+	Core language runtime
Click	Building the command‑line interface
Pytest	Running unit tests
Pydantic	Data validation and settings management

Contributing

Fork the repository, make changes in a branch, run pytest to verify, then submit a pull request.

License

MIT

Author

Matthew Snow -- [M2AI](https://m2ai.co) | [@m2ai-portfolio](https://github.com/m2ai-portfolio)