Plugin
Sistema de herramientas extensible con validación de esquemas JSON y llamada automática a funciones
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-4o'
});
// 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-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..."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[] */ ]
}
]Última actualización: 6 de julio de 2026
En esta sección
Introducción
Framework de agentes de IA de código abierto para construir sistemas autónomos que resuelven tareas del mundo real de forma eficaz.
Instalación
Instala Astreus con npm, yarn o pnpm, confirma la versión de Node.js requerida y prepara un proyecto local para construir agentes de IA con el framework.
Inicio rápido
Construye tu primer agente de IA con Astreus en menos de 2 minutos Aprende los patrones de configuración, las APIs y los ejemplos prácticos necesarios para...
Agente
Entidad de IA principal con capacidades modulares y composición basada en decoradores Aprende los patrones de configuración, las APIs y los ejemplos...