@nebulaos/rag-openai-skill

RAG (Retrieval Augmented Generation) skill for NebulaOS agents. This skill enables semantic search through OpenAI Vector Stores configured in NebulaOS Cloud.

Features

• 🔍 Semantic search through OpenAI Vector Stores
• ⚡ Simple integration with NebulaOS agents
• 🎯 Automatic tool registration
• 🔧 Configurable search parameters
• 🔐 Secure API key management

Installation

npm install @nebulaos/rag-openai-skill

Quick Start

1. Create a RAG Connection in NebulaOS Cloud

1. Navigate to the NebulaOS dashboard at /ai-features/rag
2. Click "New Connection"
3. Configure:
   • Connection name: e.g., "Support Knowledge Base"
   • OpenAI API Key
   • Vector Store ID (from OpenAI platform)
   • Search settings (maxResults, minScore)
4. Save and copy the Connection ID

2. Use in Your Agent

import { Agent, InMemory } from "@nebulaos/core";
import { OpenAI } from "@nebulaos/openai";
import { RagOpenAISkill } from "@nebulaos/rag-openai-skill";

const agent = new Agent({
  id: "support-agent",
  name: "Support Agent",
  model: new OpenAI({ model: "gpt-4" }),
  memory: new InMemory(),
  instructions: "You are a helpful support agent.",

  skills: [
    new RagOpenAISkill({
      connectionId: "conn-xyz789",
    })
  ]
});

const result = await agent.execute("How do I reset my password?");
console.log(result.content);

Configuration

RagOpenAISkillConfig

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | connectionId | string | ✅ | - | Connection ID from NebulaOS Cloud | | apiKey | string | ✅ | - | NebulaOS API key for authentication | | apiEndpoint | string | ❌ | https://api.nebulaos.com | NebulaOS Cloud API endpoint | | maxResults | number | ❌ | from connection | Override default max results | | minScore | number | ❌ | from connection | Override minimum relevance score | | timeout | number | ❌ | 30000 | Request timeout in milliseconds |

Override Search Parameters

You can override connection defaults per instance:

new RagOpenAISkill({
  connectionId: "conn-xyz789",
  apiKey: process.env.NEBULAOS_API_KEY!,
  maxResults: 10,    // Override connection default
  minScore: 0.8,     // Higher threshold for better results
})

Multiple RAG Connections

You can use multiple RAG connections in a single agent:

skills: [
  new RagOpenAISkill({
    connectionId: "conn-support",  // Support KB
    apiKey: process.env.NEBULAOS_API_KEY!,
  }),
  new RagOpenAISkill({
    connectionId: "conn-product",  // Product KB
    apiKey: process.env.NEBULAOS_API_KEY!,
  })
]

Each skill registers a unique tool that the LLM can call independently.

How It Works

1. Connection Management: NebulaOS Cloud stores your Vector Store configurations securely
2. Tool Registration: RagOpenAISkill automatically adds a search_vector_store tool to your agent
3. LLM Decision: The LLM decides when to call the search tool based on the query
4. Proxy Search: NebulaOS Cloud proxies the request to OpenAI Vector Store API
5. Results: Relevant documents are returned to the agent for use in response generation

Search Results Format

{
  results: [
    {
      content: "To reset your password, go to...",
      score: 0.92,
      metadata: { /* document metadata */ },
      source: "support-docs.pdf"
    }
  ],
  query: "reset password",
  responseTimeMs: 245
}

Error Handling

The skill includes built-in error handling:

try {
  const result = await agent.execute("query");
} catch (error) {
  // Handles:
  // - Invalid connection ID
  // - Authentication failures
  // - Network timeouts
  // - Vector store errors
}

Best Practices

1. Environment Variables: Store API keys in environment variables
2. Connection Testing: Use the Query Tester in NebulaOS dashboard to validate connections
3. Relevance Scores: Set appropriate minScore thresholds based on your use case
4. Result Limits: Balance maxResults between context size and relevance
5. Multiple Sources: Use multiple RAG connections for different knowledge domains

License

PROPRIETARY - StaryaAI