Skip to main content

​
Agent Embeddings

PraisonAI provides embedding capabilities powered by AI SDK when available, with automatic fallback to native providers. Embeddings are useful for semantic search, memory systems, and knowledge retrieval.

​
Quick Start

import { Agent } from 'praisonai';

const agent = new Agent({
  instructions: 'You are a helpful assistant',
  llm: 'openai/gpt-4o-mini'
});

// Embed single text
const embedding = await agent.embed('Hello world');
console.log('Dimensions:', embedding.length); // 1536

// Embed multiple texts
const embeddings = await agent.embed(['Hello', 'World']);
console.log('Count:', embeddings.length); // 2

​
Direct Embedding API

For more control, use the embedding functions directly: 
import { embed, embedMany, createEmbeddingProvider } from 'praisonai';

// Single embedding
const result = await embed('Hello world', {
  model: 'text-embedding-3-small',
  backend: 'ai-sdk' // or 'native' or 'auto'
});
console.log('Embedding:', result.embedding);
console.log('Tokens used:', result.usage?.tokens);

// Batch embeddings
const batchResult = await embedMany(
  ['First text', 'Second text', 'Third text'],
  { model: 'text-embedding-3-large' }
);
console.log('Embeddings:', batchResult.embeddings.length);

​
Embedding Models

​
OpenAI Models

ModelDimensionsDescription
text-embedding-3-small1536Fast, cost-effective (default)
text-embedding-3-large3072Higher quality
text-embedding-ada-0021536Legacy model

​
Google Models

ModelDimensionsDescription
text-embedding-004768Google embedding

​
Cohere Models

ModelDimensionsDescription
embed-english-v3.01024English optimized
embed-multilingual-v3.01024Multilingual support

​
Integration with Knowledge Base

Use embeddings with the KnowledgeBase for semantic search: 
import { Agent, KnowledgeBase, createEmbeddingProvider } from 'praisonai';

// Create embedding provider
const embeddingProvider = createEmbeddingProvider({
  model: 'text-embedding-3-small'
});

// Create knowledge base with embeddings
const kb = new KnowledgeBase({
  embeddingProvider,
  similarityThreshold: 0.7,
  maxResults: 5
});

// Add documents
await kb.add({ id: '1', content: 'PraisonAI is an AI agent framework' });
await kb.add({ id: '2', content: 'Embeddings enable semantic search' });

// Search
const results = await kb.search('What is PraisonAI?');
console.log('Top match:', results[0].document.content);

​
Integration with Memory

Use embeddings for semantic memory search: 
import { Memory, createEmbeddingProvider } from 'praisonai';

const memory = new Memory({
  embeddingProvider: createEmbeddingProvider(),
  maxEntries: 1000
});

// Add memories
await memory.add('User prefers dark mode', 'user');
await memory.add('User is interested in AI', 'user');

// Semantic search
const relevant = await memory.search('What does the user like?');

​
Backend Selection

PraisonAI automatically selects the best backend:
  1. AI SDK (preferred): When ai package is installed
  2. Native: Falls back to direct OpenAI client

​
Force Backend

// Force AI SDK
const result = await embed('Hello', { backend: 'ai-sdk' });

// Force native OpenAI
const result = await embed('Hello', { backend: 'native' });

// Auto-select (default)
const result = await embed('Hello', { backend: 'auto' });

​
Environment Variable

# Force backend globally
export PRAISONAI_BACKEND=ai-sdk  # or 'native' or 'auto'

​
Similarity Functions

Built-in similarity functions for comparing embeddings: 
import { cosineSimilarity, euclideanDistance } from 'praisonai';

const emb1 = await embed('Hello');
const emb2 = await embed('Hi there');

// Cosine similarity (0-1, higher = more similar)
const similarity = cosineSimilarity(emb1.embedding, emb2.embedding);
console.log('Similarity:', similarity); // ~0.9

// Euclidean distance (lower = more similar)
const distance = euclideanDistance(emb1.embedding, emb2.embedding);
console.log('Distance:', distance);

​
Performance Tips

  1. Batch embeddings: Use embedMany for multiple texts
  2. Cache embeddings: Store embeddings to avoid re-computation
  3. Choose model wisely: text-embedding-3-small is fast and cheap
// Efficient batch processing
const texts = documents.map(d => d.content);
const { embeddings } = await embedMany(texts);

// Store with documents
documents.forEach((doc, i) => {
  doc.embedding = embeddings[i];
});

​
Error Handling

try {
  const result = await embed('Hello');
} catch (error) {
  if (error.message.includes('API key')) {
    console.error('Missing OPENAI_API_KEY');
  } else if (error.message.includes('not installed')) {
    console.error('Install AI SDK: npm install ai @ai-sdk/openai');
  }
}

​
TypeScript Types

import type { 
  EmbeddingOptions, 
  EmbeddingResult, 
  EmbeddingBatchResult,
  EmbeddingProvider 
} from 'praisonai';

const options: EmbeddingOptions = {
  model: 'text-embedding-3-small',
  backend: 'auto',
  maxRetries: 2
};

const result: EmbeddingResult = await embed('Hello', options);