Skip to main content
from praisonaiagents import Agent

agent = Agent(name="registry-agent", instructions="Use the endpoint provider registry.")
agent.start("List all registered LLM endpoint providers.")
Endpoint Provider Registry lets you plug custom server-side providers (recipe, agents-api, MCP, A2A, and your own) into praisonai serve — no fork required. 
export PRAISON_ENDPOINT_URL="http://localhost:8765"
praisonai serve --endpoint mcp

from praisonai.endpoints.registry import get_provider

provider = get_provider("mcp", base_url="http://localhost:8765")
The user starts praisonai serve with a registered provider; HTTP traffic flows through discovery and the chosen endpoint adapter.

​
Quick Start

1

Use a built-in provider

from praisonai.endpoints.registry import get_provider

provider = get_provider("recipe", base_url="http://localhost:8765")
2

Register at runtime

from praisonai.endpoints.registry import register_provider
from praisonai.endpoints.providers.base import BaseProvider

class MyCustomProvider(BaseProvider):
    def __init__(self, base_url, api_key=None, **kwargs):
        self.base_url = base_url
        self.api_key = api_key

register_provider("my-custom", MyCustomProvider)
provider = get_provider("my-custom", base_url="http://localhost:8765")
3

Distribute as a pip plugin

# pyproject.toml
[project.entry-points."praisonai.endpoint_providers"]
my-custom = "mypkg.endpoints:MyCustomProvider"

pip install my-praisonai-endpoint

​
How It Works

The registry is thread-safe and loads plugins lazily. Built-ins are discovered on first access, entry points are loaded when needed, and aliases are case-insensitive. The singleton registry is obtained via get_default_registry().

​
CLI Endpoint Dispatch Registry

PraisonAI ships two endpoint registries. This page documents the top-level provider registry (praisonai.endpoint_providers). A separate CLI dispatch registry resolves how the CLI invokes each endpoint type at runtime.
RegistryEntry-point groupPurpose
Provider registry (this page)praisonai.endpoint_providersInstantiate BaseProvider classes for serve / discovery
CLI dispatch registrypraisonai.endpoints.providersMap endpoint type → bound invoke method in the CLI

​
Built-in CLI Dispatch Keys

KeyInvoke targetNotes
recipe_invoke_recipeRecipe runner endpoint
agents-api_invoke_agents_apiOpenAI Agents-API compatible
mcp_invoke_mcpMCP server endpoint
tools-mcp_invoke_mcpAlias of mcp
a2a_invoke_a2aA2A protocol
a2u_invoke_a2uA2U protocol
If you’re writing a pip plugin for CLI dispatch, use entry-point group praisonai.endpoints.providers. For the top-level provider registry (instantiating provider classes), use praisonai.endpoint_providers.

​
Configuration / API

​
Functions

Function / MethodSignatureDescription
register_provider(type, cls)(str, Type[BaseProvider]) -> NoneBackwards-compat module function; delegates to get_default_registry().register(...)
get_provider(type, base_url, api_key, **kw)(str, str, Optional[str], **Any) -> Optional[BaseProvider]Resolve + instantiate; returns None for unknown type; raises if loader fails
list_provider_types()() -> List[str]List registered + entry-point + built-in types
get_provider_class(type)(str) -> Optional[Type[BaseProvider]]Returns the class without instantiating
get_default_registry()() -> ProviderRegistryThread-safe singleton accessor

​
ProviderRegistry Class

MethodSignatureDescription
ProviderRegistry.get(type, base_url, api_key, **kw)identical to get_providerOOP-style interface
ProviderRegistry.list_types()() -> List[str]Back-compat alias for list_names()
ProviderRegistry.get_class(type)(str) -> Optional[Type]Back-compat alias for resolve()

​
Built-in Provider Types

TypeLoaded FromPurpose
recipeendpoints/providers/recipe.pyRecipe runner endpoint
agents-apiendpoints/providers/agents_api.pyOpenAI Agents-API compatible endpoint
mcpendpoints/providers/mcp.pyMCP server endpoint
tools-mcpendpoints/providers/tools_mcp.pyMCP tools-only endpoint
a2aendpoints/providers/a2a.pyA2A protocol endpoint
a2uendpoints/providers/a2u.pyA2U protocol endpoint

​
Common Patterns

Last-write-wins behavior lets you replace built-in providers:
from praisonai.endpoints.registry import register_provider
from praisonai.endpoints.providers.base import BaseProvider

class MyRecipeProvider(BaseProvider):
    def __init__(self, base_url, api_key=None, **kwargs):
        # Custom implementation
        pass

# Override built-in recipe provider
register_provider("recipe", MyRecipeProvider)
Use the underlying PluginRegistry for alias support:
from praisonai.endpoints.registry import get_default_registry

registry = get_default_registry()
registry.register_lazy("my-provider", lambda: MyProvider, aliases=["mp", "custom"])
Instantiate ProviderRegistry directly for isolation:
from praisonai.endpoints.registry import ProviderRegistry

# Tenant-specific registry
tenant_registry = ProviderRegistry()
tenant_registry.register("custom", TenantProvider)

​
Best Practices

Never import your provider class at module top-level — defeats lazy loading and breaks the no-heavy-deps-at-import-time guarantee:
# Good - lazy loader
def _load_my_provider():
    from .heavy_dependency import MyProvider
    return MyProvider

# Bad - top-level import
from .heavy_dependency import MyProvider  # Loaded immediately!
Required for type compatibility and consistent API:
from praisonai.endpoints.providers.base import BaseProvider

class MyProvider(BaseProvider):
    def __init__(self, base_url, api_key=None, **kwargs):
        super().__init__(base_url, api_key, **kwargs)
get_provider("unknown") returns None, but import failures propagate:
provider = get_provider("unknown")
if provider is None:
    print("Provider type not registered")
    
try:
    provider = get_provider("registered-but-missing-deps")
except ValueError as e:
    print(f"Provider exists but dependencies missing: {e}")
Use pyproject.toml entry points instead of register_provider() calls:
# Preferred - discoverable via pip install
[project.entry-points."praisonai.endpoint_providers"]
my-provider = "my_package.providers:MyProvider"

# Avoid - requires explicit registration
# register_provider("my-provider", MyProvider)

Integration Registry

The sibling plugin registry for CLI tools / managed agents

Framework Adapter Plugins

Third sibling plugin registry, for framework adapters