Welcome to Astreus

Astreus is a powerful and flexible AI Agent Framework designed to help you easily build, deploy, and manage intelligent conversational agents powered by large language models (LLMs).

What is Astreus?

Astreus provides a comprehensive set of tools and abstractions to create AI agents that can:

Hold complex, multi-turn conversations with real-time streaming
Manage structured chats with metadata and organization
Perform structured tasks and operations
Reason over data from multiple sources
Integrate with external systems through plugins
Maintain memory of past interactions with advanced session management
Access all components through a unified agent interface

Key Features

🤖 Agent-Centric Architecture: Everything accessible through agent methods - no need for separate managers
⚡ Real-Time Streaming: Built-in streaming chat with agent.streamChat() and agent.streamChatWithId() for live responses
💬 Advanced Chat Management: Create, organize, and manage chats with metadata using agent.createChat(), agent.listChats()
🧠 Unified Memory Access: Direct memory management with agent.getHistory(), agent.addToMemory()
📊 Session & Chat Analytics: Get insights with agent.getChatStats() and agent.searchChats()
🔌 Integrated Plugin System: Add tools with agent.addTool() and access via agent.getAvailableTools()
🗄️ Database Integration: Direct database access through agent.config.database
🎯 Provider Flexibility: Switch models with agent.getProvider() and agent.getModel()
📊 Multi-Provider Support: Works with OpenAI, Ollama, and other LLM providers
🔍 RAG Support: Built-in Retrieval Augmented Generation with automatic tool creation
🎨 Type Safety: Fully typed with TypeScript for better development experience
📝 Advanced Logging: Structured logging system for improved debugging and monitoring
⚙️ Flexible Configuration: Enhanced parameter validation and smart defaults
🔄 Lazy Table Creation: Each module creates its own database tables when first used

Agent-First Approach

With Astreus, everything revolves around the Agent with enhanced chat management:

// Create an agent with all capabilities including chat management
const agent = await createAgent({
  name: 'My Assistant',
  provider: myProvider,
  memory: myMemory,
  chat: myChatManager, // Chat management system
  tools: [customTool1, customTool2]
});

// Create and manage structured chats
const chat = await agent.createChat({
  chatId: "consultation-123",
  title: "Export Consultation",
  metadata: { type: "business", priority: "high" }
});

// Stream responses in real-time with chat IDs
await agent.streamChatWithId({
  message: "Hello!",
  chatId: "consultation-123",
  onChunk: (chunk) => console.log(chunk)
});

// Advanced chat management
const chats = await agent.listChats({ status: 'active', limit: 10 });
const stats = await agent.getChatStats();
const searchResults = await agent.searchChats({ query: "export" });

// Archive or delete chats
await agent.archiveChat("old-chat-id");
await agent.deleteChat("unwanted-chat-id");

// Access everything through the agent
const sessions = await agent.listSessions();
const history = await agent.getHistory("chat-123");
const provider = agent.getProvider();
const memory = agent.config.memory;

Database Architecture

Astreus uses a lazy table creation approach where each module automatically creates its required database tables when first used:

createMemory() creates the memories table
createChat() creates the chats table
createAgent() creates the agents table
createTask() creates the tasks table
createUser() creates the users table
createRAG() creates the RAG documents table

This eliminates the need for manual database schema setup and allows for custom table names per module.

Ready to create your first AI agent with advanced chat management? Visit our Quick Start Guide to set up Astreus and build your first conversational agent with streaming capabilities and chat organization in minutes.

Core Concepts

Agents - The heart of Astreus - unified interface for all operations including chat management
Providers - Connect to different LLM providers
Memory - Store and retrieve conversation history with session management
Chat - Advanced streaming chat system with real-time responses and metadata management
Tasks - Break complex operations into manageable sub-tasks
Plugins - Extend agent capabilities with custom tools
RAG - Automatic document search tools with Vector and Document RAG

Official Plugins

X Plugin - Interact with the X (formerly Twitter) platform
WhatsApp Plugin - Send messages via WhatsApp
Resend Plugin - Send emails through Resend
Creating Custom Plugins - Learn how to build your own plugins

How is this guide?