Astreus

Plugin

Erweiterbares Tool-System mit JSON-Schema-Validierung und automatischem Funktionsaufruf Lerne die Einrichtungsmuster, APIs und praktischen Beispiele kennen,...

Erweiterbares Tool-System mit JSON-Schema-Validierung und automatischem Funktionsaufruf

Übersicht

Plugins erweitern die Fähigkeiten von Agenten, indem sie Tools bereitstellen, die während Konversationen aufgerufen werden können. Das Plugin-System basiert auf einem Decorator-Pattern, das Agenten um Tool-Ausführungsfähigkeiten erweitert. Es bietet automatische Parametervalidierung, Fehlerbehandlung und nahtlose LLM-Integration mit Funktionsaufrufen.

Integrierte Tools

Astreus wird mit mehreren integrierten Tools ausgeliefert, die allen Agenten zur Verfügung stehen:

Knowledge-Tools

  • search_knowledge: Durchsucht die Wissensdatenbank des Agenten nach relevanten Informationen
    • query (string, erforderlich): Suchanfrage
    • limit (number, optional): Maximale Ergebnisanzahl (Standard: 5)
    • threshold (number, optional): Ähnlichkeitsschwelle (Standard: 0.7)

Vision-Tools

  • analyze_image: Allgemeine Bildanalyse mit benutzerdefinierten Prompts
  • describe_image: Erstellt barrierefreundliche Beschreibungen
  • extract_text_from_image: OCR-Funktionen zur Textextraktion

Eigene Plugins erstellen

1

Dein Tool definieren

Erstelle eine Tool-Definition mit Handler-Funktion:

import { ToolDefinition, ToolContext, ToolParameterValue } from '@astreus-ai/astreus';

const weatherTool: ToolDefinition = {
  name: 'get_weather',
  description: 'Get current weather information for a location',
  parameters: {
    location: {
      name: 'location',
      type: 'string',
      description: 'City name or location',
      required: true
    },
    units: {
      name: 'units',
      type: 'string',
      description: 'Temperature units (celsius or fahrenheit)',
      required: false
    }
  },
  handler: async (params: Record<string, ToolParameterValue>, context?: ToolContext) => {
    try {
      // Your tool implementation
      const weather = await fetchWeather(params.location as string, params.units as string);

      return {
        success: true,
        data: {
          temperature: weather.temp,
          conditions: weather.conditions,
          location: params.location
        }
      };
    } catch (error) {
      return {
        success: false,
        error: error instanceof Error ? error.message : 'Unknown error'
      };
    }
  }
};
2

Das Plugin erstellen

Bündle deine Tools zu einem Plugin:

import { Plugin, ToolParameterValue } from '@astreus-ai/astreus';

const weatherPlugin: Plugin = {
  name: 'weather-plugin',
  version: '1.0.0',
  description: 'Weather information tools',
  tools: [weatherTool],
  
  // Optional: Plugin initialization
  initialize: async (config?: Record<string, ToolParameterValue>) => {
    console.log('Weather plugin initialized');
  },
  
  // Optional: Plugin cleanup
  cleanup: async () => {
    console.log('Weather plugin cleaned up');
  }
};
3

Beim Agenten registrieren

Registriere dein Plugin bei einem Agenten:

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

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

// Register the plugin
await agent.registerPlugin(weatherPlugin);

Tool-Parametertypen

Das Plugin-System unterstützt umfassende Parametervalidierung:

// Parameter type definitions
interface ToolParameter {
  name: string;              // Parameter name
  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
  description: string;       // Parameter description
  required?: boolean;        // Whether parameter is required (optional, defaults to false)
  enum?: Array<string | number>;  // Allowed values (supports both string and number)
  properties?: Record<string, ToolParameter>; // For object types (nested properties)
  items?: ToolParameter;     // For array types (item type definition)
}

Parameterbeispiele

const advancedTool: ToolDefinition = {
  name: 'process_data',
  description: 'Process data with various options',
  parameters: {
    // String with enum values
    format: {
      name: 'format',
      type: 'string',
      description: 'Output format',
      required: true,
      enum: ['json', 'csv', 'xml']
    },
    
    // Number parameter (optional)
    limit: {
      name: 'limit',
      type: 'number',
      description: 'Maximum records to process',
      required: false
    },
    
    // Object with nested properties
    options: {
      name: 'options',
      type: 'object',
      description: 'Processing options',
      required: false,
      properties: {
        includeHeaders: {
          name: 'includeHeaders',
          type: 'boolean',
          description: 'Include column headers',
          required: false
        }
      }
    },
    
    // Array of strings
    fields: {
      name: 'fields',
      type: 'array',
      description: 'Fields to include',
      required: false,
      items: {
        name: 'field',
        type: 'string',
        description: 'Field name'
      }
    }
  },
  handler: async (params) => {
    // Tool implementation
    return { success: true, data: params };
  }
};

Tools in Konversationen verwenden

Automatische Tool-Nutzung

Agenten mit registrierten Plugins können Tools während Konversationen automatisch nutzen:

const agent = await Agent.create({
  name: 'AssistantAgent',
  model: 'gpt-4o'
});

await agent.registerPlugin(weatherPlugin);

// Agent can automatically call tools based on conversation
const response = await agent.ask("What's the weather like in Tokyo?");
// Agent will automatically call get_weather tool and incorporate results

console.log(response);
// "The current weather in Tokyo is 22°C with clear skies..."

Manuelle Tool-Ausführung

Du kannst Tools auch manuell ausführen:

// Execute single tool
const result = await agent.executeTool({
  id: 'call-123',
  name: 'get_weather',
  parameters: {
    location: 'New York',
    units: 'celsius'
  }
});

console.log(result.result.success ? result.result.data : result.result.error);

// Execute multiple tools sequentially
const results = await Promise.all([
  agent.executeTool({ id: 'call-1', name: 'get_weather', parameters: { location: 'Tokyo' } }),
  agent.executeTool({ id: 'call-2', name: 'get_weather', parameters: { location: 'London' } })
]);

Toolgestützte Tasks

Verwende Tools in strukturierten Tasks über das Task-Modul:

const task = await agent.createTask({
  prompt: "Compare the weather in Tokyo, London, and New York",
  useTools: true
});

const result = await agent.executeTask(task.id, {
  stream: true,
  onChunk: (chunk) => {
    console.log(chunk);
  }
});

Tool-Kontext und Metadaten

Tools erhalten einen Ausführungskontext mit nützlichen Informationen:

const contextAwareTool: ToolDefinition = {
  name: 'log_action',
  description: 'Log an action with context',
  parameters: {
    action: {
      name: 'action',
      type: 'string',
      description: 'Action to log',
      required: true
    }
  },
  handler: async (params, context) => {
    // Access execution context
    console.log(`Agent ${context?.agentId} performed: ${params.action}`);
    console.log(`Task ID: ${context?.taskId}`);
    console.log(`User ID: ${context?.userId}`);
    console.log(`Metadata:`, context?.metadata);
    
    return {
      success: true,
      data: { logged: true, timestamp: new Date().toISOString() }
    };
  }
};

Antworttypen

Das Verständnis der Antworten von Tool-Ausführungen hilft dir, Ergebnisse und Fehler korrekt zu behandeln.

Tool-Ausführungs-Antwort

Das Ausführen eines Tools gibt ein ToolCallResult mit Ausführungsdetails zurück:

const result = await agent.executeTool({
  id: "call-123",
  name: "get_weather",
  parameters: {
    location: "Tokyo",
    units: "celsius"
  }
});

// Response structure:
{
  id: "call-123",
  name: "get_weather",
  result: {
    success: true,
    data: {
      temperature: 22,
      conditions: "clear skies",
      location: "Tokyo",
      humidity: 65,
      wind: "5 km/h"
    }
  },
  executionTime: 250  // Execution time in milliseconds
}

Tool-Ausführung mit Fehler

Wenn ein Tool fehlschlägt, wird der Fehler in das Ergebnis aufgenommen:

const result = await agent.executeTool({
  id: "call-456",
  name: "get_weather",
  parameters: {
    location: "InvalidCity"
  }
});

// Response with error:
{
  id: "call-456",
  name: "get_weather",
  result: {
    success: false,
    error: "Location 'InvalidCity' not found"
  },
  executionTime: 150
}

Antwort bei mehrfacher Tool-Ausführung

Das Ausführen mehrerer Tools mit Promise.all gibt ein Array von Ergebnissen zurück:

const results = await Promise.all([
  agent.executeTool({ id: "call-1", name: "get_weather", parameters: { location: "Tokyo" } }),
  agent.executeTool({ id: "call-2", name: "get_weather", parameters: { location: "London" } }),
  agent.executeTool({ id: "call-3", name: "search_knowledge", parameters: { query: "climate" } })
]);

// Response structure:
[
  {
    id: "call-1",
    name: "get_weather",
    result: {
      success: true,
      data: { temperature: 22, conditions: "clear" }
    },
    executionTime: 200
  },
  {
    id: "call-2",
    name: "get_weather",
    result: {
      success: true,
      data: { temperature: 15, conditions: "cloudy" }
    },
    executionTime: 220
  },
  {
    id: "call-3",
    name: "search_knowledge",
    result: {
      success: true,
      data: [
        { content: "Climate patterns...", similarity: 0.92 },
        { content: "Global warming...", similarity: 0.85 }
      ]
    },
    executionTime: 180
  }
]

Tool-Listen-Antwort

Das Abrufen verfügbarer Tools gibt ein Array von Tool-Definitionen zurück:

const tools = agent.getTools();

// Response structure:
[
  {
    name: "get_weather",
    description: "Get current weather information for a location",
    parameters: {
      location: {
        name: "location",
        type: "string",
        description: "City name or location",
        required: true
      },
      units: {
        name: "units",
        type: "string",
        description: "Temperature units",
        required: false
      }
    },
    handler: [Function]
  },
  {
    name: "search_knowledge",
    description: "Search through the agent's knowledge base",
    parameters: { /* ... */ },
    handler: [Function]
  }
]

Plugin-Listen-Antwort

Auflisten registrierter Plugins:

const plugins = agent.listPlugins();

// Response structure:
[
  {
    name: "weather-plugin",
    version: "1.0.0",
    description: "Weather information tools",
    tools: [ /* ToolDefinition[] */ ],
    initialize: [Function],
    cleanup: [Function]
  },
  {
    name: "data-plugin",
    version: "2.1.0",
    description: "Data processing utilities",
    tools: [ /* ToolDefinition[] */ ]
  }
]

Zuletzt aktualisiert: 6. Juli 2026

In diesem Abschnitt

Einführung

Open-Source-KI-Agent-Framework zum Erstellen autonomer Systeme, die reale Aufgaben effektiv lösen.

Installation

Installiere Astreus mit npm, yarn oder pnpm, überprüfe die erforderliche Node.js-Version und bereite ein lokales Projekt für die Entwicklung von KI-Agenten...

Schnellstart

Erstelle deinen ersten KI-Agenten mit Astreus in unter 2 Minuten Lerne die Einrichtungsmuster, APIs und praktischen Beispiele kennen, die du zum Aufbau...

Agent

Zentrale KI-Entität mit modularen Fähigkeiten und dekoratorbasierter Komposition Lerne die Einrichtungsmuster, APIs und praktischen Beispiele kennen, die du...

Zurück
LLM
Weiter
MCP