Custom Plugins

Custom Plugins

Create and register custom plugins with tools for agents.

Quick Start

Clone the Complete Example

The easiest way to get started is to clone the complete example repository:

git clone https://github.com/astreus-ai/custom-plugins
cd custom-plugins
npm install

Or Install Package Only

If you prefer to build from scratch:

npm install @astreus-ai/astreus

Environment Setup

# .env
OPENAI_API_KEY=sk-your-openai-api-key-here
DB_URL=sqlite://./astreus.db

Custom Weather Plugin

import { Agent, ToolDefinition, PluginDefinition } from '@astreus-ai/astreus';

// Define a custom tool
const weatherTool: ToolDefinition = {
  name: 'get_weather',
  description: 'Get current weather for a location',
  parameters: {
    location: {
      name: 'location',
      type: 'string',
      description: 'City name',
      required: true
    },
    units: {
      name: 'units',
      type: 'string',
      description: 'Temperature units',
      required: false,
      enum: ['celsius', 'fahrenheit']
    }
  },
  handler: async (params) => {
    try {
      // Simulate weather API call
      const weather = {
        temperature: 22,
        conditions: 'sunny',
        location: params.location
      };
      
      return {
        success: true,
        data: weather
      };
    } catch (error) {
      return {
        success: false,
        error: error instanceof Error ? error.message : 'Unknown error'
      };
    }
  }
};

// Create plugin
const weatherPlugin: PluginDefinition = {
  name: 'weather-plugin',
  version: '1.0.0',
  description: 'Weather information tools',
  tools: [weatherTool]
};

// Create agent and register plugin
const agent = await Agent.create({
  name: 'WeatherAgent',
  model: 'gpt-4o'
});

await agent.registerPlugin(weatherPlugin);

// Use the plugin in conversation
const response = await agent.ask("What's the weather like in Tokyo?");
console.log(response); // Agent automatically uses the weather tool

Running the Example

If you cloned the repository:

npm run dev

If you built from scratch, create an index.ts file with the code above and run:

npx tsx index.ts

Repository

The complete example is available on GitHub: astreus-ai/custom-plugins

Last updated: September 10, 2025