Eklenti
JSON şema doğrulaması ve otomatik fonksiyon çağırmayla genişletilebilir araç sistemi
Genel Bakış#
Eklentiler (Plugins), konuşmalar sırasında çağrılabilecek araçlar sağlayarak ajan yeteneklerini genişletir. Eklenti sistemi, ajanları araç yürütme yetenekleriyle geliştiren bir decorator deseni etrafında inşa edilmiştir. Otomatik parametre doğrulama, hata yönetimi ve fonksiyon çağırmayla sorunsuz LLM entegrasyonu sağlar.
Yerleşik Araçlar#
Astreus, tüm ajanların kullanabileceği çeşitli yerleşik araçlarla birlikte gelir:
Bilgi Araçları#
- search_knowledge: İlgili bilgi için ajanın bilgi tabanında arama yapar
query(string, zorunlu): Arama sorgusulimit(number, isteğe bağlı): Maksimum sonuç (varsayılan: 5)threshold(number, isteğe bağlı): Benzerlik eşiği (varsayılan: 0.7)
Görsel Araçları#
- analyze_image: Özel promptlarla genel görüntü analizi
- describe_image: Erişilebilirlik dostu açıklamalar üretir
- extract_text_from_image: Metin çıkarımı için OCR yetenekleri
Özel Eklentiler Oluşturma#
Aracınızı Tanımlayın#
Bir handler fonksiyonuyla araç tanımı oluşturun:
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'
};
}
}
};Eklentiyi Oluşturun#
Araçlarınızı bir eklente paketleyin:
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');
}
};Ajana Kaydedin#
Eklentinizi bir ajana kaydedin:
import { Agent } from '@astreus-ai/astreus';
const agent = await Agent.create({
name: 'WeatherAgent',
model: 'gpt-6-astra'
});
// Register the plugin
await agent.registerPlugin(weatherPlugin);Araç Parametre Tipleri#
Eklenti sistemi kapsamlı parametre doğrulamayı destekler:
// 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)
}Parametre Örnekleri#
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 };
}
};Konuşmalarda Araç Kullanma#
Otomatik Araç Kullanımı#
Kayıtlı eklentilere sahip ajanlar, konuşmalar sırasında araçları otomatik olarak kullanabilir:
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..."Manuel Araç Yürütme#
Araçları manuel olarak da yürütebilirsiniz:
// 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' } })
]);Araç Destekli Görevler#
Task modülü aracılığıyla yapılandırılmış görevlerde araçlar kullanın:
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);
}
});Araç Bağlamı ve Meta Verisi#
Araçlar, yürütme sırasında faydalı bilgiler içeren bir bağlam alır:
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() }
};
}
};Yanıt Tipleri#
Araç yürütme yanıtlarını anlamak, sonuçları ve hataları düzgün biçimde işlemenize yardımcı olur.
Araç Yürütme Yanıtı#
Bir aracı yürütmek, yürütme detaylarına sahip bir ToolCallResult döndürür:
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
}Hatalı Araç Yürütme#
Bir araç başarısız olduğunda, hata sonuca dahil edilir:
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
}Çoklu Araç Yürütme Yanıtı#
Promise.all kullanarak birden fazla aracı yürütmek, sonuçlardan oluşan bir dizi döndürür:
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
}
]Araç Listesi Yanıtı#
Kullanılabilir araçları almak, araç tanımlarından oluşan bir dizi döndürür:
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]
}
]Eklenti Listesi Yanıtı#
Kayıtlı eklentileri listeleme:
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[] */ ]
}
]