Eklenti

JSON şema doğrulaması ve otomatik fonksiyon çağırmayla genişletilebilir araç sistemi Güvenilir Astreus agent sistemleri oluşturmak için gereken kurulum...

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:

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-4o'
});

// 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-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..."

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

Son güncelleme: 6 Temmuz 2026

Bu bölümde

Giriş

Gerçek dünya görevlerini etkili biçimde çözen otonom sistemler kurmak için açık kaynaklı AI ajan framework'ü.

Kurulum

Astreus'u npm, yarn veya pnpm ile kurun, gerekli Node.js sürümünü doğrulayın ve framework ile AI ajanları oluşturmak için yerel bir proje hazırlayın.

Hızlı Başlangıç

2 dakikadan kısa sürede Astreus ile ilk AI ajanınızı oluşturun Güvenilir Astreus agent sistemleri oluşturmak için gereken kurulum kalıplarını, API'leri ve...

Ajan

Modüler yetenekler ve decorator tabanlı kompozisyona sahip temel AI varlığı Güvenilir Astreus agent sistemleri oluşturmak için gereken kurulum kalıplarını,...

LLM

MCP