Skip to main content
nanobot is an open-source AI agent framework for building lightweight, composable agents with support for subagent orchestration, tool execution, and multi-step task handling.

​
Install nanobot

git clone https://github.com/HKUDS/nanobot.git
cd nanobot

pip install -e .
See the nanobot README for details.

​
OpenAlerts Plugin

AI agents fail silently — LLM errors, stuck sessions, token blowups — nobody knows until a user complains. OpenAlerts watches your agent in real-time and alerts you the moment something goes wrong.

​
Install

pip install openalerts
Add openalerts.init before your agent runs — everything is monitored automatically from that point: 
import asyncio
import openalerts
from nanobot.agent.loop import AgentLoop
from nanobot.bus.queue import MessageBus
from nanobot.providers.litellm_provider import LiteLLMProvider

async def main():
    await openalerts.init({"framework": "nanobot"})

    provider = LiteLLMProvider(api_key="sk-...", default_model="gpt-4o-mini")
    agent = AgentLoop(
        bus=MessageBus(),
        provider=provider,
        workspace="./workspace",
    )
    response = await agent.process_direct("Research quantum computing")
    print(response)

asyncio.run(main())
OpenAlerts patches nanobot internals so every LLM call, tool execution, agent step, and error flows through the monitoring engine automatically. The nanobot adapter also tracks subagent lifecycle — subagent.spawn, subagent.end, and subagent.error events are captured automatically when SubagentManager is used, with parent/child session correlation. Cleanup runs on exit. Events are persisted to ~/.openalerts/ as JSONL. To receive alerts on Slack, Discord, or a custom webhook, pass channels in the init config: 
await openalerts.init({
    "channels": [
        {"type": "slack", "webhook_url": "https://hooks.slack.com/services/..."},
        {"type": "discord", "webhook_url": "https://discord.com/api/webhooks/..."},
        {"type": "webhook", "webhook_url": "https://your-server.com/alerts"},
    ]
})
Or set environment variables instead (no code changes needed): 
OPENALERTS_SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."
OPENALERTS_DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/..."
OPENALERTS_WEBHOOK_URL="https://your-server.com/alerts"

​
Alert Rules

7 rules run against every event in real-time. All thresholds and cooldowns are configurable.
RuleWatches forSeverityDefault threshold
llm-errorsLLM/agent failures in 1 min windowERROR1 error
tool-errorsTool execution failures in 1 min windowWARN1 error
agent-stuckAgent idle too longWARN2 min
token-limitToken limit exceededERROR-
step-limit-warningAgent reaches 80% of max_stepsWARN-
high-error-rateFailure rate over last 20 callsERROR50%
subagent-errorsSubagent failures in 1 min windowWARN1 error
Every rule also accepts enabled (default true) and cooldown_seconds (default 900). To tune rules: 
await openalerts.init({
    "channels": [...],
    "rules": {
        "llm-errors": {"threshold": 5},
        "high-error-rate": {"enabled": False},
        "tool-errors": {"cooldown_seconds": 1800},
    },
    "cooldown_seconds": 900,
    "max_alerts_per_hour": 5,
})
Set "quiet": True for log-only mode (no alerts sent to channels).

​
Dashboard

A real-time web dashboard starts automatically at http://localhost:9464/openalerts:
TabWhat it shows
ActivityStep-by-step execution timeline with tool calls, LLM usage, costs
HealthRule status, alert history, system stats
DebugState snapshot for troubleshooting
By default, the dashboard runs in-process and stops when your agent exits. For a persistent dashboard, run openalerts serve in a separate terminal and disable the in-process one with "dashboard": False. Need additional help? Please reach out to us at hello@steadwing.com