Building Agents with Knowledge in Astreus

AI agents become significantly more useful when they can access and reason about your specific documents and data. Without a knowledge base, they're limited to their training data and can't answer questions about your content. Astreus enables knowledge-enhanced agents through RAG (Retrieval-Augmented Generation). Your agent automatically searches relevant documents and generates grounded, accurate responses based on your actual data. ## Quick Start Get started by cloning the complete example repository: ```bash git clone https://github.com/astreus-ai/agent-with-knowledge cd agent-with-knowledge npm install ``` Alternatively, install Astreus directly in your existing project: ```bash npm install @astreus-ai/astreus ``` ## Environment Configuration Configure your environment variables in a `.env` file: ```bash OPENAI_API_KEY=sk-your-key KNOWLEDGE_DB_URL=postgresql://user:pass@localhost:5432/knowledge_db DB_URL=sqlite://./astreus.db ``` The `OPENAI_API_KEY` provides authentication for the LLM. The `KNOWLEDGE_DB_URL` must point to a PostgreSQL database where embeddings and documents are stored for RAG functionality. The `DB_URL` handles agent persistence using SQLite or another database. ## Creating a Knowledge Agent Initialize an agent with knowledge capabilities enabled: ```typescript import { Agent } from '@astreus-ai/astreus'; const agent = await Agent.create({ name: 'CosmosBot', model: 'gpt-4o', embeddingModel: 'text-embedding-3-small', knowledge: true, systemPrompt: 'You can search and retrieve information from scientific knowledge bases about the cosmos and universe.' }); ``` Setting `knowledge: true` activates RAG features. The `embeddingModel` parameter determines which model generates vector embeddings for semantic search. Choose models that balance quality and cost for your use case. ## Adding Knowledge Sources Load documents into your agent's knowledge base: ```typescript await agent.addKnowledgeFromFile( './data/The Sun\'s Light and Heat.pdf', { category: 'solar-physics', version: '1.0' } ); ``` The `addKnowledgeFromFile()` method accepts a file path and optional metadata object. Use metadata to organize documents by category, version, or any custom fields for better filtering and retrieval. ## Using Knowledge in Conversations Query your agent and it automatically retrieves relevant information: ```typescript const response = await agent.ask("What is Correction for Atmospheric Absorption? Explain."); console.log(response); ``` The `ask()` method handles the entire RAG pipeline: converting your question to embeddings, searching the knowledge base for relevant chunks, and generating a response using the retrieved context. ## How RAG Works When you add documents, Astreus chunks them into smaller segments and creates vector embeddings. These embeddings capture semantic meaning rather than just matching keywords. During queries, your question is converted to an embedding. The system finds document chunks with similar embeddings and injects them into the LLM's context window. The agent then generates responses grounded in your actual documents, reducing hallucinations. ## Running the Example Start the development environment: ```bash npm run dev ``` The example demonstrates a complete workflow: creating an agent, loading scientific documents about solar physics, and answering domain-specific questions with accurate, sourced information. ## Key Features **Automatic Retrieval**: The agent finds relevant information without manual search commands. Just ask questions naturally. **Semantic Search**: Vector embeddings understand meaning, not just keywords. Questions like "What causes sunlight?" will match documents about solar radiation even without exact word matches. **PostgreSQL Backend**: Production-ready storage for embeddings and documents. Scale from development to production using the same `KNOWLEDGE_DB_URL` configuration. **Metadata Support**: Organize documents with custom metadata fields. Filter by category, version, topic, or any attributes relevant to your domain. ## Building Domain Experts The power of knowledge agents comes from specialized domains. Load your company's documentation, research papers, technical manuals, or any domain-specific content. Your agent becomes an expert in that specific domain, answering from authoritative sources rather than generating plausible-sounding but potentially incorrect information. This makes knowledge agents ideal for customer support, internal documentation, research assistance, and technical Q&A. ## What You've Built You now have an agent that combines LLM reasoning with custom knowledge retrieval. It searches your documents, finds relevant context, and generates accurate responses grounded in your data. Explore the complete example at github.com/astreus-ai/agent-with-knowledge to see the full implementation. This experiment is written for Astreus v0.5.37. Please ensure you are using a compatible version.