nanobot - Steadwing

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.

How do I install nanobot?

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

pip install -e .

See the nanobot README for details.

How do I set up OpenAlerts for nanobot?

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.

Rule	Watches for	Severity	Default threshold
`llm-errors`	LLM/agent failures in 1 min window	ERROR	1 error
`tool-errors`	Tool execution failures in 1 min window	WARN	1 error
`agent-stuck`	Agent idle too long	WARN	2 min
`token-limit`	Token limit exceeded	ERROR	-
`step-limit-warning`	Agent reaches 80% of max_steps	WARN	-
`high-error-rate`	Failure rate over last 20 calls	ERROR	50%
`subagent-errors`	Subagent failures in 1 min window	WARN	1 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:

Tab	What it shows
Activity	Step-by-step execution timeline with tool calls, LLM usage, costs
Health	Rule status, alert history, system stats
Debug	State 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

​How do I install nanobot?

​How do I set up OpenAlerts for nanobot?

​Install

​Alert Rules

​Dashboard

How do I install nanobot?

How do I set up OpenAlerts for nanobot?

Install

Alert Rules

Dashboard