Endpoint Provider Registry

Plug custom endpoint providers (A2A, MCP, recipe, agents-api…) into PraisonAI via Python entry points

from praisonaiagents import Agent

agent = Agent(
    name="Endpoint Agent",
    instructions="Invoke the acme endpoint provider and summarise the result."
)

agent.start("Call the acme-echo endpoint with {'x': 1}")

Endpoint Provider Registry lets you plug custom server-side providers (recipe, agents-api, MCP, A2A, openai-compat, and your own) into PraisonAI via a single Python entry-point group — no fork required.

Publish once under praisonai.endpoint_providers. One plugin is then visible to get_provider(), praisonai endpoints types, and praisonai endpoints invoke --type.

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")

A plugin published once under praisonai.endpoint_providers reaches both the provider registry and the CLI dispatch surface.

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().

One Group, Two Readers

There is one canonical entry-point group: praisonai.endpoint_providers. Two readers scan it — the top-level provider registry (instantiates BaseProvider classes for serve / discovery) and the CLI dispatch registry (resolves endpoints invoke --type). One plugin contract serves both surfaces; the CLI adapts your BaseProvider subclass into its internal dispatch shape.

Built-in Dispatch Keys

Which Group Do I Publish Under?

Migration From the Deprecated Group

Rename the entry-point group in your pyproject.toml. The class and its methods are unchanged.

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

[project.entry-points."praisonai.endpoints.providers"]
my-custom = "mypkg.endpoints:MyCustomProvider"

Deprecated-group or not, built-in names stay protected — a plugin named mcp under the legacy group cannot replace the built-in mcp provider (since PR #4185).

Constants exported by praisonai/endpoints/registry.py:

Streaming

Implement invoke_stream — not invoke(stream=True) — to support --stream. When --stream is passed the CLI adapter calls provider.invoke_stream(name, input_data, config), which yields {"event": ..., "data": ...} frames. An event == "error" frame prints the error and returns exit code 3 (runtime error); other frames print as [event] data and it returns 0.

from typing import Any, Dict, Iterator, Optional
from praisonai.endpoints.providers.base import BaseProvider, InvokeResult

class MyStreamingProvider(BaseProvider):
    def invoke(self, name, input_data=None, config=None, stream=False) -> InvokeResult:
        return InvokeResult(ok=True, status="success", data={"echo": input_data})

    def invoke_stream(
        self,
        name: str,
        input_data: Optional[Dict[str, Any]] = None,
        config: Optional[Dict[str, Any]] = None,
    ) -> Iterator[Dict[str, Any]]:
        yield {"event": "start", "data": {"name": name}}
        yield {"event": "token", "data": "hello"}
        yield {"event": "done", "data": "[DONE]"}

praisonai endpoints invoke chat_completions --type openai-compat \
  --input-json '{"messages": [{"role": "user", "content": "Hi"}]}' \
  --stream

Configuration / API

Functions

ProviderRegistry Class

Built-in Provider Types

Common Patterns

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 at runtime
register_provider("recipe", MyRecipeProvider)

from praisonai.endpoints.registry import get_default_registry

registry = get_default_registry()
registry.register_lazy("my-provider", lambda: MyProvider, aliases=["mp", "custom"])

from praisonai.endpoints.registry import ProviderRegistry

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

Best Practices

# 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!

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)

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}")

# 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)

Related