> ## Documentation Index
> Fetch the complete documentation index at: https://docs.steadwing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# nanobot

> OpenAlerts monitors your nanobot agents in real-time, detecting LLM errors, stuck agents, token blowups, subagent failures, and tool errors instantly with a live dashboard and Slack/Discord/webhook alerts.

[nanobot](https://github.com/HKUDS/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?

```bash theme={null} theme={null}
git clone https://github.com/HKUDS/nanobot.git
cd nanobot

pip install -e .
```

See the [nanobot README](https://github.com/HKUDS/nanobot) 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](https://github.com/steadwing/openalerts) watches your agent in real-time and alerts you the moment something goes wrong.

### Install

```bash theme={null} theme={null}
pip install openalerts
```

Add `openalerts.init` before your agent runs — everything is monitored automatically from that point:

```python theme={null} theme={null}
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:

```python theme={null} theme={null}
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):

```bash theme={null} theme={null}
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:

```python theme={null} theme={null}
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](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](mailto:hello@steadwing.com)