Integration Registry

Add custom CLI / managed-agent / hosted-agent integrations via Python entry points

from praisonaiagents import Agent

agent = Agent(name="registry-agent", instructions="Manage integrations via the registry.")
agent.start("List all registered integrations and their status.")

The user installs a third-party package; entry points register CLI and agent backends in one registry.

Integration Registry enables third-party developers to add custom CLI tools, managed agents, and agent backends to PraisonAI through a centralized plugin system.

Quick Start

1. Use a built-in integration

   from praisonai.integrations import ClaudeCodeIntegration
   
   integration = ClaudeCodeIntegration(workspace="/path/to/project")
   
2. Register at runtime

   # Preferred (lazy — no registry built until first call)
   from praisonai.integrations._unified_registry import get_integrations_registry
   
   def _my_loader():
       from my_pkg.integration import MyIntegration
       return MyIntegration
   
   get_integrations_registry().register_lazy("MyIntegration", _my_loader, aliases=["my"])
   
   # Now this works:
   from praisonai.integrations import MyIntegration
   
3. Distribute as a pip plugin

   # pyproject.toml of your third-party package
   [project.entry-points."praisonai.integrations"]
   MyIntegration = "my_pkg.integration:MyIntegration"
   

   pip install my-praisonai-integration
   

   # Now this works in any praisonai-using project:
   from praisonai.integrations import MyIntegration
   

---

How It Works

Before PR #1763, praisonai/integrations/__init__.py had a 70-line if/elif ladder in __getattr__ that mapped attribute names to lazy imports. After #1763, the ladder is replaced by a 4-line dispatch backed by INTEGRATIONS_REGISTRY. The registry:

• Subclasses the generic PluginRegistry[T] from praisonai._registry
• Loads built-in integrations lazily (CLI tools, managed agents, sandboxed agents, hosted/local agent backends, registry helpers)
• Supports third-party integrations via the new entry-point group praisonai.integrations — distribute a pip package, no code changes to praisonai
• Exposes a get_by_attr(module_name, attr_name) helper that raises AttributeError (not ValueError) so the dispatch slots into module-level __getattr__

---

Configuration / API

Method	Parameters	Description
get_integrations_registry()	→ IntegrationRegistry	Return the process-default registry, building it lazily on first call (thread-safe)
INTEGRATIONS_REGISTRY.register_lazy(name, loader, *, aliases=None)	name: str, loader: () -> Any, aliases: list[str] | None	Register a lazily-loaded integration
INTEGRATIONS_REGISTRY.resolve(name)	name: str → Any	Materialize an integration; ValueError if unknown
INTEGRATIONS_REGISTRY.get_by_attr(module, attr)	module: str, attr: str → Any	Same as resolve but raises AttributeError (for use inside __getattr__)

INTEGRATIONS_REGISTRY remains available as a module-level name for backward compatibility — the first access triggers construction. Use get_integrations_registry() in new code to make the lazy build explicit. Underscore-prefixed submodule names (for example from praisonai.integrations import _unified_registry) now import normally instead of triggering registry construction.

---

Built-in Integrations

The registry includes these built-in integrations with lazy loading:

CLI Tools

• ClaudeCodeIntegration — Claude Code CLI integration
• GeminiCLIIntegration — Gemini CLI tools
• CodexCLIIntegration — Codex CLI interface
• CursorCLIIntegration — Cursor CLI integration
• BaseCLIIntegration — Base class for CLI tools
• CLIExecutionError — CLI execution error class

Managed Agents

• ManagedAgent (alias: ManagedAgentIntegration) — Managed agent interface
• AnthropicManagedAgent — Anthropic-specific managed agent
• ManagedConfig (alias: ManagedBackendConfig) — Managed agent configuration

Local & Sandboxed Agents

• LocalManagedAgent — Local managed agent
• LocalManagedConfig — Local agent configuration
• SandboxedAgent — Sandboxed agent execution
• SandboxedAgentConfig — Sandboxed agent configuration

Agent Backends

• HostedAgent — Hosted agent backend
• HostedAgentConfig — Hosted agent configuration
• LocalAgent — Local agent backend
• LocalAgentConfig — Local agent configuration

Registry Functions

• get_available_integrations — List available integrations
• ExternalAgentRegistry — External agent registry
• get_registry — Get integration registry
• register_integration — Register new integration
• create_integration — Create integration instance

---

Advanced Usage

Adding a New Built-in Backend

Built-in CLI backends (Claude Code, Gemini, Codex, Cursor) are registered from a single canonical module: praisonai/integrations/_cli_loaders.py. It exports CLASS_NAME_LOADERS (class-name → loader) used by IntegrationRegistry, and BUILTIN_INTEGRATIONS (short-alias → loader) used by ExternalAgentRegistry. Register a new built-in backend in one place and both registry surfaces pick it up.

Build Your Own Namespace

Use create_lazy_getattr(registry) from praisonai._registry for plugin authors who want to give their own package the same lazy-loading + entry-point dispatch behaviour:

# my_pkg/__init__.py
from praisonai._registry import PluginRegistry, create_lazy_getattr

_REG = PluginRegistry(entry_point_group="my_pkg.plugins")
__getattr__ = create_lazy_getattr(_REG)

---

Common Patterns

Override a Built-in

from praisonai.integrations._unified_registry import get_integrations_registry

def _my_loader():
    from my_pkg import MyClaudeCodeIntegration
    return MyClaudeCodeIntegration

# Override built-in
get_integrations_registry().register_lazy("ClaudeCodeIntegration", _my_loader)

Last-write-wins on the canonical name.

Multiple Aliases

get_integrations_registry().register_lazy(
    "MyIntegration", 
    _loader, 
    aliases=["my", "mi", "custom"]
)

Both the alias and the canonical name resolve.

Multi-tenant Isolation

from praisonai.integrations._unified_registry import IntegrationRegistry

# Per-tenant registry (not the singleton)
tenant_registry = IntegrationRegistry()
tenant_registry.register_lazy("TenantTool", _loader)

Construct your own IntegrationRegistry() for per-tenant registration that doesn’t leak.

---

Best Practices

Always Use Lazy Loading

Always use a _loader function, never import the integration at module top-level — that defeats the lazy-loading:

# ✅ Good
def _my_loader():
    from my_pkg.integration import MyIntegration
    return MyIntegration

# ❌ Bad - imports at module level
from my_pkg.integration import MyIntegration
def _my_loader():
    return MyIntegration

Use Canonical Names

Names are case-insensitive; pick the canonical form (matching the class name) for the registration key:

# ✅ Good - matches class name
get_integrations_registry().register_lazy("MyIntegration", _loader)

# ❌ Confusing - different case
get_integrations_registry().register_lazy("myintegration", _loader)

Avoid Internal Imports

Don’t bypass the registry to import internal integration modules directly — those paths are not part of the public API:

# ✅ Good - use the public API
from praisonai.integrations import ClaudeCodeIntegration

# ❌ Bad - internal import path
from praisonai.integrations.claude_code import ClaudeCodeIntegration

---

Related

Framework Adapter Plugins

Plugin system for multi-agent frameworks

Persistence Backend Plugins

Add custom storage backends