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 sorgusu
    • limit (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:

typescript
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:

typescript
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:

typescript
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:

typescript
// 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#

typescript
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:

typescript
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:

typescript
// 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:

typescript
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:

typescript
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:

typescript
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:

typescript
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:

typescript
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:

typescript
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:

typescript
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[] */ ]
  }
]