agorum core ai tools entwickeln

Ein KI-Tool in agorum core ai agents ist entweder ein JavaScript-Tool oder ein Tool, das über einen MCP-Server verwendet wird. Diese Dokumentation beschreibt die Erstellung eines JavaScript-KI-Tools, also eines Tools für Aktionen in agorum core, das von dem verbundenen KI-Sprachmodell ausgeführt werden kann.

Ein eigenes Java-Script-KI-Tool erstellen

Die Einrichtung eines JavaScript-KI-Tools besteht aus den folgenden beiden wesentlichen Schritten:

1. Erstellen des JavaScripts
2. Einrichten der Tool-Definition

Voraussetzung: Bevor Sie mit der eigentlichen Entwicklung beginnen, sollten Sie überlegen, wo Sie Ihre KI-Tools verwalten wollen. Sie sollten die KI-Tools in einem eigenen Konfigurationsprojekt ablegen, damit sie sie gut verwalten und in andere Systeme überführen können. 

1. Erstellen Sie in Ihrem Konfigurationsprojekt einen Unterordner ai im Ordner js: js/ai/tools.
2. Erstellen Sie in diesem neuen Ordner eine JavaScript-Datei mit folgendem JavaScript-Grundgerüst als Inhalt und speichern Sie die Datei, etwa unter dem Namen hello-world.js. 
3. Öffnen Sie  > Administration > Konfiguration > KI-Tools.
   
   Ergebnis: Das Fenster Tool einrichten öffnet sich.
4. Klicken Sie auf die Schaltfläche (Plus), um eine neue Konfiguration zu erstellen.
   
   Ergebnis: Das Fenster Neues Tool anlegen öffnet sich. 
5. Geben Sie einen wiedererkennbaren Namen an, der nur Kleinbuchstaben, Zahlen und Unterstriche enthält. Erstellen Sie die Tool-Definition in dem Konfigurationsprojekt, in dem auch der eben erstellte JavaScript-Code liegt. 
6. Geben Sie als Handler in der KI-Tool-Definition den Pfad zur JavaScript-Datei an. 
7. Speichern Sie die KI-Tool-Definition. In der KI-Tool-Definition sehen Sie die KI-Tool-Informationen, die Sie in der FUNCTION_DEFINITION festgelegt haben.
   
   Ergebnis: Sie haben Ihr erstes eigenes KI-Tool erstellt. Dieses KI-Tool hilft Ihnen, die Funktionsweise zu verstehen. Auf dieser Grundlage können Sie eigene KI-Tools mit mehr Funktionalität entwickeln.
8. Klicken Sie auf Validieren/Testen und validieren und testen Sie die geänderte Konfiguration mit Testeinstellungen.
   
   Ergebnis: Das Fenster Tool validieren und ausführen öffnet sich.
9. Jetzt haben Sie zwei Möglichkeiten:
   
   • Validieren: Testet, ob das Tool mit den angegebenen Parametern ausgeführt werden kann. Sie erhalten ggf. eine Fehlermeldung, falls nicht alle erforderlichen Parameter ausgefüllt sind oder die Angaben nicht verwendet werden können.
   • Ausführen: Das Tool wird mit den angegebenen Parametern ausgeführt. Das Fenster Rückgabe des Tools öffnet sich und enthält die zurückgegebenen JSON-Daten.
10. Stellen Sie sicher, dass die Tool-Konfiguration aktiv ist bzw. der Haken bei Tool ist aktiv und kann genutzt werden gesetzt ist.
11. Erstellen Sie eine KI-Voreinstellung, die im Chat verwendet werden kann und das Tool verwendet, siehe KI-Voreinstellungen einrichten.
    
    Ergebnis: Sie können das Tool im Chat verwenden.

     

    

    Verwenden des Hello World-Tools im Chat

 

Grundgerüst eines KI-Tools

// Importing necessary modules. 
// `tools` provides utility functions, and `fs` is used for function schema definition and validation.
let tools = require('/agorum/roi/customers/agorum.ai.agents/js/lib/tools');
let fs = require('/agorum/roi/customers/agorum.ai.agents/js/lib/function-schema')();

/**
 * Definition of parameters for the AI tool.
 * The function schema specifies the expected input parameters and their descriptions.
 */
let FUNCTION_DEFINITION = fs.defineFunction({
  name: 'hello_world',
  displayName: 'A simple hello world tool',
  description: 'Creates a hello world message and appends the user message',
  // Schema definition specifies the expected input parameters for the tool.
  inputSchema: fs
    .object()
    .property(
      // Mandatory parameter 'message' that will be appended to the "Hello World" statement.
      'message',
      fs.string().description('A message, that is appended to the hello world message').minLength(5),
      true
    )
    .property(
      // Optional parameter 'additionalMessage' for adding more content to the hello message.
      'additionalMessage',
      fs.string().description('An additional message, that is appended to the hello world message').minLength(1),
      false
    ),
});

// This object contains the functions related to the AI tool.
({
  /**
   * Generates a description of the tool's schema, potentially filtering out some parameters.
   *
   * @param {[Object]} toolParams - Optional parameters that, if provided, will be removed from the resulting schema description.
   * @return {Object} The descriptive schema object for other AI tools to utilize.
   */
  getDescription: toolParams => tools.buildFunctionDescription(FUNCTION_DEFINITION, toolParams),

  /**
   * Executes the tool using the provided parameters.
   *
   * @param {[Object]} params - The complete set of parameters provided for tool execution.
   * @return {String|Object} A concatenated "Hello World" message with user inputs or a validation result if input fails.
   */
  run: params => {
    // Validate the input parameters against the schema definition.
    let vResult = fs.validate(params, FUNCTION_DEFINITION);
    if (vResult) {
      // Return validation errors if input parameters are incorrect.
      return vResult;
    }

    // Generate and return a combined "Hello World" message using the input parameters.
    return 'Hello World: "' + params.message + '": ' + (params.additionalMessage ? params.additionalMessage : '');
  },
});

Feld	Beschreibung
name	Interner, sprechender Name der Funktion, idealerweise in Kleinbuchstaben mit Unterstrichen.
displayName	Anzeigename.
description	Erklärung der Funktion und ihres Verwendungszwecks. Diese Information ist wichtig für die KI, um das Tool gegebenenfalls zu finden und auszuwählen. Die Beschreibung sollte daher umfassend und klar formuliert sein. Die Beschreibung kann sehr ausführlich sein und Informationen zur Verwendung des Tools für die KI sein.  Sie sollten die Beschreibung, vor allem wenn sie länger ist, im Markdown-Format erstellen.
inputSchema	Definition der Tool-Parameter. Die möglichen Angaben sind im Funktionsschema festgelegt. Parameter mit definierten Angaben, entweder im Code oder in der Konfiguration werden nicht an die KI übergeben.

Anzeige der KI-Tool-Definitionen in der KI-Tool-Konfiguration

Sie sehen im folgenden Screenshot, dass die in der Funktionsdefinition angegebenen Parameter im KI-Tool angzeigt und getestet werden können.

Funktionsschema

Das Funktionsschema, das in der Bibliothek agorum.ai.agents/js/lib/function-schema definiert ist, legt fest, welche inputSchema Sie in der Funktionsdefinition verwenden können. Darüber haben Sie verschiedene Möglichkeiten, die erwarteten Eingabeparameter präzise zu spezifizieren.

Objektschema

Sie können ein Objektschema erstellen, um mehrere Eigenschaften zu definieren, die das Eingabeschema erfüllen muss.

inputSchema: fs.object()

Eigenschaften innerhalb eines Objektschemas

property(name, schema, required)

Definiert eine Eigenschaft im Objekt mit einem Namen, einer Typdefinition (Schema) und einem Flag, ob diese Eigenschaft erforderlich ist.

 

Beispiele:

  inputSchema: fs
    .object()
    .property(
      'username',
      fs.string().description('The unique username for the account.').minLength(3).maxLength(20),
      true // required
    )
    .property(
      'email',
      fs.string().description("The user's email address.").format('email'), // uses the 'email' format for validation
      true // required
    ),

Verwendung spezifischer Typen

 

String-Schema

Methoden: 

• minLength(n)
• maxLength(n)
• pattern(regex)
• format(fmt)
• enum(values)

 

Beispiel:

  inputSchema: fs
    .object()
    .property(
      'inputString',
      fs.string().description('A valid alphanumeric string.').minLength(5).maxLength(20).pattern('^[a-zA-Z0-9]+$'), // Nur alphanumerische Zeichen
      true // required
    ),

 

Number- und Integer-Schema 

Methoden:

• minimum(n)
• maximum(n)
• exclusiveMinimum(n)
• exclusiveMaximum(n)
• multipleOf(n)

 

Beispiel:

  inputSchema: fs
    .object()
    .property(
      'discountRate',
      fs.number().description('Discount rate as a percentage.').minimum(0).maximum(100), // percentage
      true // required
    )
    .property(
      'customerID',
      fs.integer().description('Unique customer identifier.').minimum(1), // ID must be positive
      false // optional
    ),

 

Boolean-Schema 

Beispiel:

  inputSchema: fs.object().property(
    'isActive',
    fs.boolean().description('Indicates whether the field should be active.'),
    true // required
  ),

 

Array-Schema

Methoden:

• minItems(n)
• maxItems(n)
• uniqueItems(bool)

 

Beispiel:

  inputSchema: fs.object().property(
    'tags',
    fs
      .array(fs.string().maxLength(10)) // Array of string elements, each with max 10 characters
      .description('List of tags associated with the resource.')
      .minItems(1) // Minimum one tag required
      .uniqueItems(true), // Tags must be unique
    true // required
  ),

 

Besondere Bedingungen

additionalProperties gibt an, ob zusätzliche, nicht definierte Eigenschaften im Objekt erlaubt sind.

fs.object().additionalProperties(false)

Beispiel mit einem REST-Aufruf im Tool

Die folgenden Code-Beispiele zeigen, wie Sie ein KI-Tool einrichten können, das eine externe API über einen REST-Aufruf anspricht. In diesem Fall werden die aktuellen Wetterdaten abgerufen. 

Folgen Sie den oben beschriebenen Schritten zur Einrichtung eines eigenen KI-Tools: 

1. Erstellen Sie die JavaScript-Dateien in Ihrem Konfigurationsprojekt unter dem Pfad: ⁣js/ai/tools
2. Erstellen Sie eine neue KI-Tool-Definition, die auf die Datei get-weather-by-city.js als Handler verweist.
3. Fügen Sie das neue Tool zu der KI-Voreinstellung hinzu, in der Sie es verwenden wollen.

Beispiel-Skript für den REST-Client

weather-api.js

let json = require('client/json');

/**
 * Retrieves weather data from any weather API.
 * @param {string} url - The base URL of the weather API (e.g. 'https://api.open-meteo.com/v1/forecast')
 * @param {object} params - An object with query parameters (e.g. {latitude: 48.137, longitude: 11.575, current_weather: true})
 * @param {object} [options] - Optional: Additional options for the request (e.g. headers, authentication)
 * @returns {object} - The result of the API query as a JavaScript object
 */
let getWeather = (url, params, options) => {
  let service = json(url, {
    type: 'application/json',
    accept: 'application/json',
  })('/');

  if (options && options.header) {
    for (let key in options.header) {
      service.header(key, options.header[key]);
    }
  }

  if (options && options.basicAuth) {
    let auth = options.basicAuth;
    service.basicAuth(auth.username, auth.password);
  }

  if (params) {
    service.query(params);
  }
  let response = service.get();
  return response;
};

/**
 * Searches for the coordinates of a city using the Open-Meteo Geocoding API.
 * @param {string} city - Name of the city
 * @returns {object|null} - Object with latitude and longitude or null if not found
 */
let getCoordinatesByCity = city => {
  let geoService = json('https://geocoding-api.open-meteo.com/v1', {
    type: 'application/json',
    accept: 'application/json',
  })('/search');

  geoService.query({ name: city, count: '1', language: 'de', format: 'json' });

  let geoResult = geoService.get();
  if (geoResult && geoResult.results && geoResult.results.length > 0) {
    let first = geoResult.results[0];
    return { latitude: first.latitude, longitude: first.longitude };
  }
  return null;
};

/**
 * Retrieves weather data for a city.
 * @param {string} city - Name of the city
 * @param {object} [options] - Optional: Additional options for the request (e.g. headers, authentication)
 * @returns {object|null} - The result of the weather API or null if the city was not found
 */
let getWeatherByCity = (city, options) => {
  let coords = getCoordinatesByCity(city);
  if (!coords) {
    return null;
  }
  let params = { latitude: coords.latitude, longitude: coords.longitude, current_weather: true };
  return getWeather('https://api.open-meteo.com/v1/forecast', params, options);
};

exports.getWeatherByCity = getWeatherByCity;

Beispiel-Skript für ein KI-Tool mit Verwendung eines REST-Clients

get-weather-by-city.js

/**
 * AI tool to query the weather of a city
 */
let weatherApi = require('/agorum/roi/customers/agorum.doc.test/js/ai/weather-api');
let fs = require('/agorum/roi/customers/agorum.ai.agents/js/lib/function-schema')();
let tools = require('/agorum/roi/customers/agorum.ai.agents/js/lib/tools');

/**
 * Definition of the parameters for this tool
 */
let FUNCTION_DEFINITION = fs.defineFunction({
  name: 'get_weather_by_city',
  displayName: 'Weather query for a city',
  description: 'Returns the current weather for a specified city',
  inputSchema: fs
    .object()
    .property(
      'city',
      fs.string().description('Name of the city for which the weather should be queried').minLength(1),
      true
    ),
});

// Definition of the functions of this tool
({
  /**
   * Returns the tool description as inputSchema for the AI tools
   *
   * @param {[Object]} toolParams - Optional tool parameters. Each parameter defined here will be removed from the function description
   */
  getDescription: toolParams => fs.toolDescription(FUNCTION_DEFINITION, toolParams),

  /**
   * Executes the weather query for the specified city
   *
   * @param {[Object]} params - The complete parameters from tool and AI
   */
  run: params => {
    let vResult = fs.validate(params, FUNCTION_DEFINITION);
    if (vResult) return vResult;

    let city = params.city;
    let weather = weatherApi.getWeatherByCity(city);
    if (!weather) {
      return tools.error('No weather data could be found for the city ' + city + '.');
    }

    return weather;
  },
});

Beispiele für die weitere Verwendung