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.

Get started by cloning the complete example repository:

BashCopy
git clone https://github.com/astreus-ai/agent-with-knowledge
cd agent-with-knowledge
npm install

Alternatively, install Astreus directly in your existing project:

BashCopy
npm install @astreus-ai/astreus

Configure your environment variables in a .env file:

BashCopy
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.

Initialize an agent with knowledge capabilities enabled:

TypeScriptCopy
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.

Load documents into your agent's knowledge base:

TypeScriptCopy
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.

Query your agent and it automatically retrieves relevant information:

TypeScriptCopy
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.

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.

Start the development environment:

BashCopy
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.

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.

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.

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.