Provider Registry

Register and use custom LLM providers in PraisonAI TypeScript SDK

The Provider Registry allows you to register custom LLM providers that can be used with createProvider(). This enables integration with any LLM provider beyond the built-in OpenAI, Anthropic, and Google providers.

Registered providers apply to both chat and embeddings. As of PraisonAI PR #4874, a provider registered via registerProvider(...) (or registerCustomProvider(...)) is resolved through the same createAISDKProvider(...) code path for embedding calls — agent.embed(...), embed(...), and embedMany(...) — as for chat. Embeddings used to be the lone exception; #4874 unified them.

Quick Start

1. Simple Usage

   import { registerProvider, createProvider, BaseProvider } from 'praisonai';
   
   // Define a custom provider
   class CloudflareProvider extends BaseProvider {
     readonly providerId = 'cloudflare';
   
     async generateText(options) {
       // Your implementation
     }
   
     async streamText(options) {
       // Your implementation
     }
   
     async generateObject(options) {
       // Your implementation
     }
   
     formatTools(tools) {
       // Your implementation
     }
   
     formatMessages(messages) {
       // Your implementation
     }
   }
   
   // Register the provider
   registerProvider('cloudflare', CloudflareProvider);
   
   // Use it like any built-in provider
   const provider = createProvider('cloudflare/workers-ai-model');
   
2. With Configuration

   import { registerProvider, createProvider } from 'praisonai';
   
   registerProvider('custom', CustomProvider);
   const provider = createProvider('custom/model');
   

API Reference

registerProvider

Register a custom provider to the global registry.

import { registerProvider } from 'praisonai';

registerProvider(name: string, provider: ProviderConstructor | ProviderLoader, options?: RegisterOptions);

Parameters:

• name - Provider name (e.g., ‘cloudflare’, ‘ollama’)
• provider - Provider class or factory function
• options - Optional configuration
  • override - Allow overwriting existing registration (default: false)
  • aliases - Additional names that resolve to this provider

Example with aliases:

registerProvider('cloudflare', CloudflareProvider, {
  aliases: ['cf', 'workers-ai']
});

// All of these now work:
createProvider('cloudflare/model');
createProvider('cf/model');
createProvider('workers-ai/model');

Providers registered on the default registry are visible to both the async (resolveBackend) and sync (resolveBackendSync) code paths. Prior to praisonai@1.7.5, native ESM callers of the sync path silently saw a second, empty registry — a registerProvider('stub', StubProvider) there was invisible to a following resolveBackendSync('stub/…'), which returned Unknown provider: 'stub'. Fixed by PraisonAI PR #4720.

createProvider

Create a provider instance from various input types.

import { createProvider } from 'praisonai';

// String format: "provider/model"
const provider = createProvider('openai/gpt-4o');

// String format with default provider detection
const provider = createProvider('gpt-4o-mini'); // Defaults to OpenAI

// Provider instance (pass-through)
const provider = createProvider(existingProvider);

// Spec object
const provider = createProvider({
  name: 'openai',
  modelId: 'gpt-4o',
  config: { timeout: 5000 }
});

getDefaultRegistry

Get the global provider registry instance.

import { getDefaultRegistry } from 'praisonai';

const registry = getDefaultRegistry();
console.log(registry.list()); // ['openai', 'anthropic', 'google']

createProviderRegistry

Create an isolated registry instance for multi-agent safety.

import { createProviderRegistry, registerBuiltinProviders } from 'praisonai';

const isolatedRegistry = createProviderRegistry();
registerBuiltinProviders(isolatedRegistry);

// Register custom providers only to this registry
isolatedRegistry.register('custom', CustomProvider);

// Use with createProvider
const provider = createProvider('custom/model', { registry: isolatedRegistry });

listProviders

List all registered provider names.

import { listProviders } from 'praisonai';

console.log(listProviders()); // ['openai', 'anthropic', 'google']

hasProvider

Check if a provider is registered.

import { hasProvider } from 'praisonai';

console.log(hasProvider('openai')); // true
console.log(hasProvider('cloudflare')); // false (until registered)

unregisterProvider

Remove a provider from the registry.

import { unregisterProvider } from 'praisonai';

unregisterProvider('custom-provider');

Built-in Providers

The following providers are registered by default:

Provider	Aliases	Environment Variable
openai	oai	OPENAI_API_KEY
anthropic	claude	ANTHROPIC_API_KEY
google	gemini	GOOGLE_API_KEY

Creating a Custom Provider

Extend BaseProvider to create a custom provider:

import { BaseProvider, ProviderConfig, GenerateTextOptions, GenerateTextResult } from 'praisonai';

class OllamaProvider extends BaseProvider {
  readonly providerId = 'ollama';
  private baseUrl: string;

  constructor(modelId: string, config?: ProviderConfig) {
    super(modelId, config);
    this.baseUrl = config?.baseUrl || 'http://localhost:11434';
  }

  async generateText(options: GenerateTextOptions): Promise<GenerateTextResult> {
    const response = await fetch(`${this.baseUrl}/api/generate`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        model: this.modelId,
        prompt: options.messages.map(m => m.content).join('\n'),
        stream: false
      })
    });

    const data = await response.json();
    return {
      text: data.response,
      usage: {
        promptTokens: 0,
        completionTokens: 0,
        totalTokens: 0
      }
    };
  }

  async *streamText(options: StreamTextOptions): AsyncGenerator<StreamChunk> {
    // Streaming implementation
  }

  async generateObject<T>(options: GenerateObjectOptions<T>): Promise<GenerateObjectResult<T>> {
    // Object generation implementation
  }

  formatTools(tools: ToolDefinition[]): any[] {
    return tools;
  }

  formatMessages(messages: Message[]): any[] {
    return messages;
  }
}

// Register and use
registerProvider('ollama', OllamaProvider);
const provider = createProvider('ollama/llama2');

Lazy Loading

Providers can be registered with lazy loading for better startup performance:

registerProvider('heavy-provider', () => {
  // This code only runs when the provider is first used
  const { HeavyProvider } = require('./heavy-provider');
  return HeavyProvider;
});

Multi-Agent Safety

Use isolated registries when running multiple agents that need different provider configurations:

import { createProviderRegistry, registerBuiltinProviders, createProvider } from 'praisonai';

// Agent 1's registry
const agent1Registry = createProviderRegistry();
registerBuiltinProviders(agent1Registry);
agent1Registry.register('custom', Agent1CustomProvider);

// Agent 2's registry
const agent2Registry = createProviderRegistry();
registerBuiltinProviders(agent2Registry);
agent2Registry.register('custom', Agent2CustomProvider);

// Each agent uses its own provider
const agent1Provider = createProvider('custom/model', { registry: agent1Registry });
const agent2Provider = createProvider('custom/model', { registry: agent2Registry });

Error Handling

The registry provides clear error messages:

try {
  createProvider('unknown-provider/model');
} catch (error) {
  // Error: Unknown provider: 'unknown-provider'. 
  // Available providers: openai, anthropic, google.
  // Register a custom provider with registerProvider('unknown-provider', YourProviderClass).
}

TypeScript Types

import type {
  ProviderConstructor,
  ProviderLoader,
  RegisterOptions,
  IProviderRegistry,
  ProviderInput,
  CreateProviderOptions
} from 'praisonai';

Related

Providers

Built-in LLM providers

Provider Registry CLI

CLI management