# Custom Plugins
URL: /docs/examples/custom-plugins
Source: /app/src/content/docs/examples/custom-plugins.mdx

import { DocImage } from '@/components/DocImage';

<DocImage title="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:

```bash
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:

```bash
npm install @astreus-ai/astreus
```

## Environment Setup

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

## Custom Weather Plugin

```typescript
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:

```bash
npm run dev
```

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

```bash
npx tsx index.ts
```

## Repository

The complete example is available on GitHub: [astreus-ai/custom-plugins](https://github.com/astreus-ai/custom-plugins)