nanobot

Nanobot implements a BaseChannel abstraction layer that normalizes message I/O across 25+ messaging platforms (Telegram, Feishu, Matrix, Discord, WeChat, Slack) and a CLI REPL, routing all user inputs through a centralized message bus and event flow system. Each channel adapter handles platform-specific authentication, message formatting, and delivery semantics while the core AgentLoop processes normalized message objects, enabling a single agent instance to serve multiple communication channels simultaneously without code duplication.

Nanobot implements a ProviderSpec registry pattern that abstracts 25+ LLM services (OpenAI, Anthropic, Ollama, Groq, etc.) behind a unified interface. The system uses native SDKs for major providers (OpenAI, Anthropic) and a centralized metadata registry for auto-detection of model capabilities, token limits, and cost parameters. Provider selection is declarative via config schema, with fallback logic for API key resolution from environment variables or config files, enabling seamless switching between LLM backends without code changes.

Nanobot uses a declarative YAML configuration schema (defined in config/schema.py) that specifies agent behavior, LLM provider, channels, tools, memory settings, and automation rules. The configuration loader supports environment variable interpolation (e.g., ${OPENAI_API_KEY}), schema validation via Pydantic, and config migration/backfilling for backward compatibility. Configuration is loaded at startup and can be reloaded without restarting the agent, enabling dynamic reconfiguration.

Nanobot provides a feature-rich CLI REPL (built with typer and prompt-toolkit) that enables interactive agent interaction with command routing, history, autocomplete, and syntax highlighting. The CLI supports built-in commands (e.g., /memory, /tools, /config) for agent introspection and control, while regular text is routed to the agent for processing. The REPL maintains conversation history and integrates with the agent's session management, allowing users to interact with the agent from the terminal.

Nanobot supports Docker containerization via a Dockerfile that packages the agent with all dependencies, enabling consistent deployment across environments. The system supports multi-instance deployment where multiple agent instances can run concurrently (e.g., in Kubernetes), each with its own configuration and session state. The message bus and channel layer coordinate across instances, and external storage (database, Redis) can be used for shared state (sessions, memory, configuration).

Nanobot implements security controls at the tool layer: file operations are restricted to configured directories via path validation, shell commands can be whitelisted to prevent arbitrary execution, and network requests can be filtered by URL patterns. The security layer validates all tool inputs before execution and logs security events for audit trails. Network security includes configurable headers, timeout limits, and SSL verification to prevent SSRF and other attacks.

Nanobot supports creating subagents that can be spawned by parent agents to handle specialized tasks. Subagents are configured similarly to parent agents (with their own LLM provider, tools, memory) and communicate with parent agents via the message bus. Parent agents can delegate tasks to subagents, wait for results, and incorporate subagent responses into their own reasoning. This enables hierarchical agent structures where complex tasks are decomposed across multiple specialized agents.

The AgentLoop orchestrates the core agent execution cycle: it receives a user message, builds context from memory and session history, sends a prompt to the LLM, parses tool calls from the response, executes tools, and loops until the agent decides to respond or hits a configurable iteration limit (default 200 iterations). Context building dynamically incorporates session history, memory consolidation results, and available tool schemas, with each iteration step tracked for debugging and memory consolidation.

Nanobot implements a two-tier memory architecture: session-based history stores recent interactions in memory, while a 'Dream' consolidation process periodically compresses history into long-term facts via LLM summarization. The DreamConfig defines consolidation triggers (time-based, message-count-based, or manual), and the system maintains separate storage for raw history and consolidated facts, allowing agents to retain context over long conversations without unbounded token growth.

Nanobot provides a built-in tool registry with three core tools: shell execution (subprocess-based command running), file operations (read/write/list with path validation), and web access (HTTP requests with configurable headers and timeouts). Tools are registered as callable functions with JSON schema definitions, enabling the LLM to invoke them via tool-calling APIs. Each tool includes safety checks (path validation for files, command whitelisting for shell) and error handling that returns structured results to the agent.

Nanobot integrates with the Model Context Protocol (MCP) standard, allowing agents to dynamically load external tools via stdio or HTTP transports. The MCP integration layer handles protocol negotiation, tool discovery, and invocation, enabling agents to access tools from external services (e.g., Anthropic's MCP servers) without modifying core agent code. Tools discovered via MCP are registered in the same tool registry as built-in tools, making them transparent to the agent loop.

Nanobot includes a Cron Service that enables agents to schedule recurring tasks using cron expressions (e.g., '0 9 * * *' for daily 9 AM execution). The service maintains a schedule registry, triggers tasks at specified times, and invokes agent callbacks (AgentHook lifecycle callbacks) to execute custom logic. Scheduled tasks can invoke tools, send messages to channels, or trigger memory consolidation, enabling agents to perform background work without user interaction.

Nanobot implements a Heartbeat Service that periodically sends keep-alive signals to connected channels and monitors connection health. The service detects disconnections, triggers reconnection logic, and maintains session continuity across network interruptions. Heartbeat intervals are configurable per channel, and the service integrates with the message bus to coordinate health checks across multiple concurrent channel connections.

Nanobot manages session lifecycles by tracking session state (active, idle, closed), maintaining session metadata (creation time, last activity, user context), and implementing cleanup logic for expired sessions. Sessions are created per user or conversation thread, and the system tracks session state transitions through the message bus. Expired sessions trigger memory consolidation and cleanup callbacks, enabling graceful session termination and resource reclamation.

Nanobot provides a high-level Python SDK (Nanobot.from_config()) that enables embedding agents into Python applications without CLI overhead. The SDK exposes AgentHook lifecycle callbacks for custom logic at key points (agent startup, message processing, tool invocation, memory consolidation), allowing developers to integrate agents into larger systems. The SDK returns a Nanobot facade object with methods for sending messages, querying state, and managing the agent lifecycle programmatically.