Tool Source Registry

This page is about publishing whole ToolSource implementations — a lower-level extensibility point for the resolver itself. If you just want to publish an individual tool so agents can call it by name, use the canonical praisonai.tools entry-point group instead (see Tool Discovery Order).

ToolSourceRegistry lets a Python package expose new tool-resolution sources through the praisonai.tool_sources entry-point group — no subclassing, no monkey-patching.

from praisonaiagents import Agent

# Once `pip install praisonai-corp-tools` is done, corp-tools registers
# itself via the praisonai.tool_sources entry point. Nothing else to wire up.
agent = Agent(
    name="Finance Bot",
    instructions="Use corporate tools to answer",
    tools=["corp.pay_invoice"],   # resolved through the plugin source
)
agent.start("Pay invoice INV-42 for $1200")

The user asks to pay an invoice; the plugin entry point resolves corporate tools without extra wiring.

Quick Start

Simple usage

Install a plugin package, then use tool names from that source on any agent:

pip install praisonai-corp-tools

from praisonaiagents import Agent

agent = Agent(
    name="Finance Bot",
    instructions="Use corporate tools to answer",
    tools=["corp.pay_invoice"],
)
agent.start("Pay invoice INV-42 for $1200")

Direct Python (DI)

Construct a ToolResolver with source_registry= to isolate a tenant or a test:

from praisonai.tool_resolver import ToolResolver, ToolSourceRegistry

registry = ToolSourceRegistry()          # discovers praisonai.tool_sources plugins
resolver = ToolResolver(source_registry=registry)
tool = resolver.resolve("corp.pay_invoice")

How It Works

Resolution walks the built-in chain first (local tools.py, wrapper registry, praisonaiagents.tools, praisonai-tools, core SDK registry), then each ToolSource from ToolSourceRegistry. Entry-point sources are appended to the built-in chain — they extend rather than replace it. When you pass sources= explicitly, entry-point sources are not appended; you fully own the chain.

Built-in names win. ToolSourceRegistry subclasses the base PluginRegistry, so since PraisonAI PR #4176 publishing a praisonai.tool_sources entry point whose name (case-insensitive) matches an already-shipped built-in source has no effect — the entry point is skipped, the shipped source resolves, and a DEBUG line notes the collision. Use runtime register(...) for a deliberate override. See Plugin Precedence.

Building a Tool Source Plugin

Implement the `ToolSource` protocol

# praisonai_corp_tools/source.py
from typing import Callable, Optional

_CORP_TOOL_MAP: dict[str, Callable] = {}

class CorpToolsSource:
    name = "corp-tools"

    def lookup(self, name: str) -> Optional[Callable]:
        if not name.startswith("corp."):
            return None
        short = name.removeprefix("corp.")
        return _CORP_TOOL_MAP.get(short)

Register the entry point in `pyproject.toml`

[project.entry-points."praisonai.tool_sources"]
corp-tools = "praisonai_corp_tools.source:CorpToolsSource"

The entry-point value may be:

a ToolSource class (instantiated once — CorpToolsSource),
a factory function returning a ToolSource instance, or
an already-constructed ToolSource instance.

Factory example:

[project.entry-points."praisonai.tool_sources"]
corp-tools = "praisonai_corp_tools.source:build_source"

import os

def build_source():
    return CorpToolsSource(base_url=os.environ["CORP_URL"])

Ship it

After pip install, the source is live in every ToolResolver that uses the process-default registry (or any resolver you construct with a registry that discovers entry points). To verify from the CLI immediately after pip install, run praisonai tools add <package> --dry-run — it constructs a fresh resolver and prints exactly which tools now resolve. See tools add.

Configuration Options

Option	Where	Type	Default	Description
`source_registry`	`ToolResolver(...)` constructor	`Optional[ToolSourceRegistry]`	Process-default registry (lazy)	Registry supplying third-party entry-point tool sources. Pass an empty registry to opt out.
`discover_entry_points`	`ToolSourceRegistry(...)` constructor	`bool`	`True`	When `False`, the registry does not scan the `praisonai.tool_sources` entry-point group on construction. Use for tests or a hard opt-out.

Common Patterns

Opt out of third-party sources
Isolate a plugin for a specific tenant
Deterministic tests

from praisonai.tool_resolver import ToolResolver, ToolSourceRegistry

empty = ToolSourceRegistry(discover_entry_points=False)
resolver = ToolResolver(source_registry=empty)
# Only the built-in chain is used; installed plugins are ignored.

from praisonai.tool_resolver import ToolResolver, ToolSourceRegistry

class TenantToolsSource:
    name = "tenant-tools"

    def lookup(self, name: str):
        return None

registry = ToolSourceRegistry(discover_entry_points=False)
registry.register("tenant-tools", TenantToolsSource)

resolver = ToolResolver(source_registry=registry)

Use discover_entry_points=False so tests stay reproducible regardless of what is installed in the environment — the same pattern as test_tool_source_registry.py in the PraisonAI SDK:

from praisonai.tool_resolver import ToolResolver, ToolSourceRegistry

registry = ToolSourceRegistry(discover_entry_points=False)
registry.register("fake", MyTestSource)

resolver = ToolResolver(source_registry=registry)
assert resolver.resolve("fake_tool") is not None

Safety

A plugin that raises during loading is logged and skipped — resolution never breaks for other callers.
A plugin that resolves to an object not matching the ToolSource protocol (missing name: str or callable lookup) is rejected with a TypeError inside _coerce_source and skipped — it never gets appended to the chain.
Behaviour is covered by test_misbehaving_plugin_is_skipped and test_invalid_shape_plugin_is_skipped in the SDK test suite.

Best Practices

Namespace your tool names

Use a prefix like corp. so plugin tools do not collide with built-in names.

Return None fast for names you do not own

lookup() runs in chain order; bail out quickly when a name is not yours.

Never raise from lookup() for expected misses

Raise only for genuine errors — the registry logs and skips your source on failure, so a raise looks like a broken plugin.

Avoids stale process-wide state in long-running services.

Tool Resolver

Single source of truth for loading tools

Persistence Backend Plugins

Same PluginRegistry pattern for stores

Framework Adapter Plugins

Entry-point plugins for execution frameworks

Registry Dependency Injection

Registry DI pattern across the wrapper

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Tool Source Registry

Quick Start

How It Works

Building a Tool Source Plugin

Implement the `ToolSource` protocol

Register the entry point in `pyproject.toml`

Ship it

Configuration Options

Common Patterns

Safety

Best Practices

Tool Resolver

Persistence Backend Plugins

Framework Adapter Plugins

Registry Dependency Injection

​Quick Start

​How It Works

​Building a Tool Source Plugin

​Implement the ToolSource protocol

​Register the entry point in pyproject.toml

​Ship it

​Configuration Options

​Common Patterns

​Safety

​Best Practices

​Related

Tool Resolver

Persistence Backend Plugins

Framework Adapter Plugins

Registry Dependency Injection

Quick Start

How It Works

Building a Tool Source Plugin

Implement the `ToolSource` protocol

Register the entry point in `pyproject.toml`

Ship it

Configuration Options

Common Patterns

Safety

Best Practices

Related