Plugin
Système d'outils extensible avec validation de schéma JSON et appel automatique de fonctions
Vue d'ensemble#
Les plugins étendent les capacités des agents en fournissant des outils qui peuvent être appelés pendant les conversations. Le système de plugins est construit autour d'un modèle de décorateur qui enrichit les agents avec des capacités d'exécution d'outils. Il offre une validation automatique des paramètres, une gestion des erreurs, et une intégration transparente avec l'appel de fonctions du LLM.
Outils intégrés#
Astreus est livré avec plusieurs outils intégrés disponibles pour tous les agents :
Outils de connaissances#
- search_knowledge : recherche dans la base de connaissances de l'agent des informations pertinentes
query(string, requis) : requête de recherchelimit(number, optionnel) : nombre maximum de résultats (par défaut : 5)threshold(number, optionnel) : seuil de similarité (par défaut : 0.7)
Outils Vision#
- analyze_image : analyse générale d'image avec des invites personnalisées
- describe_image : génère des descriptions favorisant l'accessibilité
- extract_text_from_image : capacités OCR pour l'extraction de texte
Créer des plugins personnalisés#
Définir votre outil#
Créez une définition d'outil avec une fonction de gestion (handler) :
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'
};
}
}
};Créer le plugin#
Regroupez vos outils dans un 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');
}
};Enregistrer auprès de l'agent#
Enregistrez votre plugin auprès d'un agent :
import { Agent } from '@astreus-ai/astreus';
const agent = await Agent.create({
name: 'WeatherAgent',
model: 'gpt-6-astra'
});
// Register the plugin
await agent.registerPlugin(weatherPlugin);Types de paramètres d'outil#
Le système de plugins prend en charge une validation complète des paramètres :
// 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)
}Exemples de paramètres#
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 };
}
};Utiliser les outils dans les conversations#
Utilisation automatique des outils#
Les agents avec des plugins enregistrés peuvent automatiquement utiliser des outils pendant les conversations :
const agent = await Agent.create({
name: 'AssistantAgent',
model: 'gpt-6-astra'
});
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..."Exécution manuelle des outils#
Vous pouvez également exécuter des outils manuellement :
// 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' } })
]);Tâches enrichies d'outils#
Utilisez des outils dans des tâches structurées via le module Task :
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);
}
});Contexte et métadonnées des outils#
Les outils reçoivent un contexte d'exécution avec des informations utiles :
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() }
};
}
};Types de réponse#
Comprendre les réponses d'exécution d'outils vous aide à gérer correctement les résultats et les erreurs.
Réponse Tool Execution#
Exécuter un outil retourne un ToolCallResult avec les détails d'exécution :
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 Execution avec erreur#
Lorsqu'un outil échoue, l'erreur est incluse dans le résultat :
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
}Réponse Multiple Tool Execution#
Exécuter plusieurs outils avec Promise.all retourne un tableau de résultats :
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
}
]Réponse Tool List#
Récupérer les outils disponibles retourne un tableau de définitions d'outils :
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]
}
]Réponse Plugin List#
Lister les plugins enregistrés :
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[] */ ]
}
]