AstrBot

AstrBot implements a platform adapter abstraction layer that normalizes incoming messages from Discord, Telegram, QQ, and web chat into a unified internal message format, then routes responses back through platform-specific adapters. The system uses a connection mode abstraction supporting both webhook and polling patterns, with message component transformation that converts platform-native rich content (embeds, reactions, files) into a standardized AST-like structure for processing. This enables a single agent pipeline to serve heterogeneous chat platforms without duplicating business logic.

AstrBot implements a provider abstraction layer that unifies access to multiple LLM backends (OpenAI, Anthropic, Gemini, Ollama, local models) through a common interface. The system manages provider lifecycle (initialization, authentication, model selection), handles streaming responses with token-level granularity, implements context compression strategies to fit conversations within token limits, and provides automatic retry logic with exponential backoff. Provider configuration separates sources (API credentials) from instances (model + parameter combinations), enabling multi-model deployments and A/B testing without credential duplication.

AstrBot implements a hierarchical configuration system that loads settings from YAML/JSON files, environment variables, and runtime API calls. The system supports configuration hot-reloading without application restart, environment variable interpolation (e.g., `${OPENAI_API_KEY}`), configuration validation against schemas, and configuration versioning. Configuration is organized into sections (platform settings, provider settings, feature flags, etc.), with defaults provided for all settings. The configuration API allows runtime updates to settings, which are persisted to disk and applied immediately.

AstrBot implements a media handling layer that normalizes file uploads and attachments across platforms, stores files in a configurable backend (local filesystem, S3, etc.), and transforms media for platform-specific requirements. The system handles file type validation, size limits, virus scanning (optional), and generates platform-specific attachment objects (Discord embeds, Telegram InputFile, etc.). The file service provides a unified API for uploading, downloading, and deleting files, with support for temporary files and automatic cleanup.

AstrBot implements an i18n system that supports multiple languages for UI, agent responses, and system messages. Language packs are loaded from JSON/YAML files, with support for pluralization, variable interpolation, and context-specific translations. The system detects user language from platform metadata (Discord locale, Telegram language_code) or explicit user preference, and applies translations at the UI and agent level. Theming system allows customization of dashboard appearance (colors, fonts, layout) via configuration files.

AstrBot implements a dual-mode tool execution system: native function tools defined via Python decorators or JSON schemas, and remote MCP (Model Context Protocol) servers for standardized tool discovery and execution. The system maintains a tool registry, validates tool call arguments against schemas, executes tools in an isolated sandbox context with restricted access to system resources, and handles tool results with error recovery. MCP integration enables tools to be defined in any language and discovered dynamically, while native tools provide low-latency execution for performance-critical operations.

AstrBot implements a plugin architecture (called 'Stars') built on an event bus that decouples plugins from core systems. Plugins register event handlers and commands at startup, can be loaded/unloaded dynamically without restarting the application, and persist configuration in a plugin-specific storage layer. The system includes a plugin marketplace for discovery and installation, automatic dependency resolution, and a context API that provides plugins with access to agent state, configuration, and platform adapters. Hot reload enables rapid iteration during development by reloading plugin code without losing application state.

AstrBot implements a multi-stage message processing pipeline that routes incoming messages through security/filtering stages (content moderation, rate limiting, permission checks), a main agent processing stage (LLM inference + tool execution), and result decoration stages (formatting, embedding generation, response assembly). Each stage is pluggable and can be extended or replaced. The pipeline uses an async/await pattern for non-blocking I/O and supports streaming responses where intermediate results are sent to the user before the full response is complete. Pipeline stages have access to a shared context object containing message metadata, agent state, and configuration.

AstrBot implements a hierarchical agent system where a main agent can delegate tasks to subagents based on intent classification or explicit routing rules. Agents are composed of skills (reusable task templates) and tools, with configuration-driven agent instantiation. The system manages agent lifecycle (initialization, context setup, execution), handles agent-to-agent communication via a message queue, and provides a unified execution interface that abstracts whether a task is handled locally or delegated to a subagent. Agent context includes conversation history, user metadata, and access to platform adapters.

AstrBot implements a knowledge base layer that stores documents, embeddings, and metadata in a vector database. The system supports semantic search via embedding similarity, retrieval-augmented generation (RAG) where relevant documents are injected into the LLM context, and configurable chunking strategies for long documents. Knowledge bases can be populated via file upload, web scraping, or API integration. The RAG pipeline automatically retrieves relevant documents based on user queries and injects them into the agent's system prompt or conversation history, enabling the agent to answer questions grounded in custom knowledge.

AstrBot implements a persona system that allows configuration of agent personality, tone, response style, and behavioral constraints via YAML/JSON configuration files. Personas are injected into the system prompt and influence agent behavior across all interactions. The system supports persona switching at runtime, persona composition (combining multiple personas), and persona-specific tool restrictions. Personas can be versioned and shared across multiple agents, enabling consistent personality across deployments.

AstrBot includes a web-based dashboard (built with modern frontend framework) that provides UI for managing LLM providers, configuring platform connections, installing/managing plugins, viewing conversation history, and monitoring system health. The dashboard uses dynamic configuration components that adapt to provider-specific settings (e.g., OpenAI vs. Anthropic parameters). The backend exposes REST APIs for all dashboard operations, enabling programmatic configuration management. The dashboard supports real-time updates via WebSocket for monitoring agent execution and system metrics.

AstrBot implements a conversation persistence layer that stores message history in a database, with support for multi-turn conversations, session management, and context routing via UMOP (User-Message-Operation-Platform) keys. The system automatically manages conversation context (selecting relevant history for LLM context), implements sliding window and summarization strategies for long conversations, and supports conversation search and retrieval. Sessions are scoped by user, platform, and conversation ID, enabling multi-platform conversation continuity (e.g., user starts conversation on Discord, continues on Telegram).