Tool Factory Registry

Register tool builders and construct tool instances from user config

The factory registry stores builders that construct tool instances from config — use it when you have “here’s how to build this tool from user config”, not “I already have my tool”.

Quick Start

1. Register a Factory

   import { registerToolFactory } from 'praisonai';
   
   registerToolFactory(
     {
       id: 'web-search',
       name: 'web_search',
       packageName: '@my-org/web-search',
       tags: ['search'],
       requiredEnv: ['SEARCH_API_KEY'],
       capabilities: {},
       install: { npm: 'npm install @my-org/web-search' },
     },
     (config) => createWebSearchTool(config),
   );

2. Build an Instance

   import { createToolInstance } from 'praisonai';
   
   const tool = createToolInstance('web-search', { maxResults: 5 });

Migration from the Old Root Exports

Before PR #4902, register_tool / get_tool / validate_tool at the package root pointed at the factory registry by accident. They now point at the name-keyed registry. If you actually wanted the factory registry, switch names:

// Before — these root names were the factory registry by accident:
import { register_tool, get_tool } from 'praisonai';

// Now those names are the name-keyed registry. For the factory registry, use:
import {
  registerToolFactory,
  createToolInstance,
  tryCreateToolInstance,
} from 'praisonai';

Building Instances

Two builders, differing only in how they report a missing id.

import { createToolInstance, tryCreateToolInstance } from 'praisonai';

// Throws ToolNotRegisteredError for an unknown id.
const tool = createToolInstance('web-search', { apiKey });

// Returns null for a missing id (still throws ToolConstructionError if the
// factory itself fails).
const maybe = tryCreateToolInstance('web-search', { apiKey });
if (maybe) {
  await maybe.execute({ query: 'praisonai' });
}

See Tool Errors for the try/catch pattern that tells “missing” apart from “broken”.

Pre-flight Checks

validateToolInstall(id) reports whether a registered tool’s npm dependency and required environment variables are in place — ideal for CLIs and setup scripts.

import { validateToolInstall } from 'praisonai';

const status = await validateToolInstall('web-search');
// { valid, installed, missingEnvVars, errors }

if (!status.valid) {
  console.error(status.errors.join('\n'));
}

Registry API

Access the singleton for advanced use cases.

import { getToolsRegistry, createToolsRegistry } from 'praisonai';

const registry = getToolsRegistry();
registry.list();               // all metadata
registry.has('web-search');    // presence check
registry.getMetadata('web-search');

// An isolated registry for tests or multi-agent scenarios
const scoped = createToolsRegistry();

Best Practices

Related