Praison AI

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.

Diagram

Developer

Registry

Provider

Quick Start

  1. Simple Usage
    typescript
    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
    typescript
    import { registerProvider, createProvider } from 'praisonai';

registerProvider('custom', CustomProvider);
const provider = createProvider('custom/model');

API Reference

registerProvider

Register a custom provider to the global registry.

typescript
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:

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

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

createProvider

Create a provider instance from various input types.

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

typescript
import { getDefaultRegistry } from 'praisonai';

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

createProviderRegistry

Create an isolated registry instance for multi-agent safety.

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

typescript
import { listProviders } from 'praisonai';

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

hasProvider

Check if a provider is registered.

typescript
import { hasProvider } from 'praisonai';

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

unregisterProvider

Remove a provider from the registry.

typescript
import { unregisterProvider } from 'praisonai';

unregisterProvider('custom-provider');

Built-in Providers

The following providers are registered by default:

ProviderAliasesEnvironment Variable
openaioaiOPENAI_API_KEY
anthropicclaudeANTHROPIC_API_KEY
googlegeminiGOOGLE_API_KEY

Creating a Custom Provider

Extend BaseProvider to create a custom provider:

typescript
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:

typescript
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:

typescript
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:

typescript
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

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

Related

Providers

Built-in LLM providers

 Provider Registry CLI

CLI management