PraisonAI supports a simplified plugin format inspired by WordPress - just a single Python file with metadata in a docstring header.
Single-file plugins are the easiest way to extend PraisonAI with custom tools and hooks. No package structure, no configuration files - just one .py file.
Create a file in ~/.praisonai/plugins/ or ./.praison/plugins/:
Copy
"""Plugin Name: Weather ToolsDescription: Get weather information for any cityVersion: 1.0.0Author: Your Name"""from praisonaiagents import tool@tooldef get_weather(city: str) -> str: """Get the current weather for a city. Args: city: Name of the city Returns: Weather information string """ # Your implementation here return f"The weather in {city} is sunny, 72°F"@tooldef get_forecast(city: str, days: int = 5) -> str: """Get weather forecast for a city. Args: city: Name of the city days: Number of days to forecast Returns: Forecast information """ return f"{days}-day forecast for {city}: Sunny with occasional clouds"
from praisonaiagents import Agent# Tools are auto-discovered from plugin directoriesagent = Agent( name="Weather Assistant", instructions="Help users with weather information", tools=["get_weather", "get_forecast"] # Reference by name)response = agent.start("What's the weather in Paris?")
# Create a new plugin with templatepraisonai plugins init my_plugin# With optionspraisonai plugins init weather_tools --author "John Doe" --with-hook# In a specific directorypraisonai plugins init custom --output ./my_plugins/
Copy
# List all discovered pluginspraisonai plugins scan# With detailspraisonai plugins scan --verbose# JSON outputpraisonai plugins scan --json
Copy
# Load a specific plugin filepraisonai plugins load ./my_plugin.py# Discover and load all pluginspraisonai plugins discover --verbose
Copy
# Print a plugin template to stdoutpraisonai plugins template# Save to filepraisonai plugins template > my_plugin.py# With hook examplepraisonai plugins template --with-hook
from praisonaiagents import ( load_plugin, discover_plugins, discover_and_load_plugins,)# Load a single pluginresult = load_plugin("./my_plugin.py")print(f"Loaded: {result['name']}, tools: {result['tools']}")# Discover plugins without loadingplugins = discover_plugins(["./plugins", "~/.praisonai/plugins"])for p in plugins: print(f"Found: {p['name']} at {p['path']}")# Discover and load allloaded = discover_and_load_plugins(include_defaults=True)print(f"Loaded {len(loaded)} plugins")