Plugin
Sistema de herramientas extensible con validación de esquemas JSON y llamada automática a funciones
Descripción general#
Los plugins amplían las capacidades de los agentes proporcionando herramientas que pueden invocarse durante las conversaciones. El sistema de plugins se basa en un patrón de decoradores que dota a los agentes de capacidades de ejecución de herramientas. Ofrece validación automática de parámetros, manejo de errores e integración fluida con la llamada a funciones del LLM.
Herramientas integradas#
Astreus incluye varias herramientas integradas disponibles para todos los agentes:
Herramientas de conocimiento#
- search_knowledge: busca en la base de conocimiento del agente información relevante
query(string, obligatorio): consulta de búsquedalimit(number, opcional): resultados máximos (por defecto: 5)threshold(number, opcional): umbral de similitud (por defecto: 0.7)
Herramientas de visión#
- analyze_image: análisis general de imágenes con prompts personalizados
- describe_image: genera descripciones accesibles
- extract_text_from_image: capacidades OCR para extracción de texto
Crear plugins personalizados#
Define tu herramienta#
Crea una definición de herramienta con función controladora (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'
};
}
}
};Crea el plugin#
Agrupa tus herramientas en 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');
}
};Regístralo con el agente#
Registra tu plugin con un agente:
import { Agent } from '@astreus-ai/astreus';
const agent = await Agent.create({
name: 'WeatherAgent',
model: 'gpt-6-astra'
});
// Register the plugin
await agent.registerPlugin(weatherPlugin);Tipos de parámetros de herramienta#
El sistema de plugins soporta una validación completa de parámetros:
// 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)
}Ejemplos de parámetros#
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 };
}
};Usar herramientas en las conversaciones#
Uso automático de herramientas#
Los agentes con plugins registrados pueden usar herramientas automáticamente durante las conversaciones:
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..."Ejecución manual de herramientas#
También puedes ejecutar herramientas manualmente:
// 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' } })
]);Tareas potenciadas con herramientas#
Usa herramientas en tareas estructuradas mediante el módulo 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);
}
});Contexto y metadatos de la herramienta#
Las herramientas reciben un contexto de ejecución con información útil:
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() }
};
}
};Tipos de respuesta#
Entender las respuestas de ejecución de herramientas te ayuda a manejar los resultados y errores correctamente.
Respuesta de ejecución de herramienta#
Ejecutar una herramienta devuelve un ToolCallResult con los detalles de la ejecución:
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
}Ejecución de herramienta con error#
Cuando una herramienta falla, el error se incluye en el resultado:
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
}Respuesta de ejecución de múltiples herramientas#
Ejecutar varias herramientas con Promise.all devuelve un array de resultados:
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
}
]Respuesta de lista de herramientas#
Recuperar las herramientas disponibles devuelve un array de definiciones de herramienta:
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]
}
]Respuesta de lista de plugins#
Listar los plugins registrados:
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[] */ ]
}
]