<!-- source: https://deepwiki.com/MervinPraison/PraisonAI/5.4-custom-tools-and-plugins -->

# Custom Tools and Plugins

- api.md
- src/praisonai-agents/praisonaiagents/__init__.py

## Purpose and Scope

This page provides a comprehensive guide for creating custom tools and packaging them as pip-installable plugins for PraisonAI agents. It covers the tool definition mechanisms (`@tool` decorator and `BaseTool` class), plugin packaging standards, and the auto-discovery system that makes tools available to agents.

For information about using existing tools and built-in tool integration, see [Tool Integration](/MervinPraison/PraisonAI/5.1-tool-integration). For protocol-based tool systems, see [MCP Protocol](/MervinPraison/PraisonAI/5.2-mcp-protocol) and [A2A Protocol](/MervinPraison/PraisonAI/5.3-a2a-protocol).

## Tool Creation Overview

PraisonAI provides two primary mechanisms for creating custom tools that agents can execute:

### Tool Creation Flow

```

```

**Sources:** [README.md70](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L70-L70) [README.md394](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L394-L394) [api.md119-126](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L119-L126)

## Creating Tools with @tool Decorator

The `@tool` decorator converts any Python function into a tool that agents can call. The decorator automatically generates JSON schema from type hints and docstrings.

### Basic Tool Definition

```

```

### Tool Function Requirements

### Tool Parameter Types

The decorator supports standard Python types and Pydantic models:

```

```

### Tool with Context and State

Tools can access execution context and maintain state:

```

```

**Sources:** [api.md126](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L126-L126) [README.md394](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L394-L394)

## Creating Tools with BaseTool Class

For more complex tools requiring validation, error handling, or stateful operations, subclass `BaseTool`:

### BaseTool Structure

```

```

### BaseTool Implementation Example

```

```

### BaseTool vs @tool Comparison

**Sources:** [api.md119-126](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L119-L126) [README.md394](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L394-L394)

## Packaging Tools as Plugins

To make tools reusable across projects and shareable with the community, package them as pip-installable plugins.

### Plugin Package Structure

```
my-praison-tools/
|-- setup.py
|-- pyproject.toml
|-- README.md
|-- LICENSE
`-- praison_tools_mypackage/
    |-- __init__.py
    |-- math_tools.py
    |-- api_tools.py
    `-- data_tools.py
```

### Setup Configuration (setup.py)

```

```

### Modern Configuration (pyproject.toml)

```

```

### Tool Module Implementation

```

```

### Package init .py

```

```

**Sources:** [README.md394](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L394-L394)

## Auto-Discovery Mechanisms

PraisonAI uses Python entry points to automatically discover and load tools from installed packages.

### Tool Discovery Flow

```

```

### Manual Tool Discovery

For development or custom loading scenarios:

```

```

### Tool Registry Architecture

```

```

### Tool Naming Conventions

**Sources:** [api.md119-126](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L119-L126) [README.md394](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L394-L394)

## Tool Lifecycle and Execution

### Tool Execution Pipeline

```

```

### Tool Execution Context

Tools receive context during execution:

```

```

### Async Tool Execution

Both sync and async tools are supported:

```

```

**Sources:** [api.md39-40](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L39-L40) [README.md394](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L394-L394)

## Advanced Tool Features

### Tool with Dependency Injection

```

```

### Tool Result Validation

```

```

### Tool Error Handling Patterns

```

```

### Tool Composition

Create higher-level tools by composing simpler tools:

```

```

**Sources:** [api.md39-40](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L39-L40) [README.md394](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L394-L394)

## Testing Custom Tools

### Unit Testing Tools

```

```

### Integration Testing with Agents

```

```

### Mock Testing for External Dependencies

```

```

**Sources:** [README.md394](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L394-L394)

## Best Practices

### Tool Design Principles

### Security Considerations

```

```

### Performance Optimization

```

```

**Sources:** [README.md394](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L394-L394)

## Publishing and Distribution

### Publishing to PyPI

```

```

### Tool Package Metadata

Include comprehensive metadata for discoverability:

```

```

### Documentation Requirements

Create clear documentation for your tools:

```

```

## Tools

### calculate_statistics

Calculate statistical measures for a list of numbers.

**Parameters:**

- numbers (List[float]): List of numeric values

**Returns:**

- Dictionary with mean, median, std_dev, min, max

**Example:**

```

```

```

**Sources:** <FileRef file-url="https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L394-L394" min=394  file-path="README.md">Hii</FileRef>

---

## Summary

Custom tools and plugins extend PraisonAI agents with domain-specific capabilities. Key takeaways:

1. **Creation**: Use `@tool` decorator for simple functions, `BaseTool` class for complex tools
2. **Packaging**: Follow standard Python packaging with entry points for auto-discovery
3. **Discovery**: Tools are automatically loaded from installed packages via `praisonai.tools` entry point group
4. **Execution**: Tools execute within agent context with validation, error handling, and async support
5. **Best Practices**: Focus on single responsibility, type safety, comprehensive error messages, and security

For using existing tools, see [Tool Integration](#5.1). For protocol-based tools, see [MCP Protocol](#5.2) and [A2A Protocol](#5.3).

**Sources:** <FileRef file-url="https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L70-L70" min=70  file-path="README.md">Hii</FileRef> <FileRef file-url="https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L394-L394" min=394  file-path="README.md">Hii</FileRef> <FileRef file-url="https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L119-L126" min=119 max=126 file-path="api.md">Hii</FileRef>
```
