Clientseitige Tools

Clientseitige Tools werden im Browser oder in der Hostanwendung des Benutzers ausgeführt und ermöglichen den Zugriff auf lokale Clientdaten und Gerätefunktionen, die auf Serverseite nicht verfügbar sind.

Clientseitige Tools werden auf der Clientoberfläche – dem Browser oder der Hostanwendung des Benutzers – und nicht auf dem UiPath-Server ausgeführt. Wenn der Agent ein clientseitiges Tool aufruft, pausiert die Runtime, delegiert den Toolaufruf an den Client und wird fortgesetzt, sobald der Client ein Ergebnis zurückgibt.

Verwenden Sie clientseitige Tools, wenn der Agent Zugriff auf Daten oder Funktionen benötigt, die nur auf dem Client vorhanden sind, z. B. auf den Anwendungsstatus, lokale Daten oder UI-Aktionen, die nicht serverseitig ausgeführt werden können.

Wann clientseitige Tools verwendet werden sollten

Verwenden Sie clientseitige Tools, wenn der Agent:

• Zugriff auf lokale Clientdaten – Lesen Sie Informationen aus der Hostanwendung, die für den Server nicht verfügbar sind, z. B. den Inhalt eines Taskboards, Formularfelder oder einen sitzungsspezifischen Status.
• Clientseitige Aktionen auslösen – Führen Sie Aktionen innerhalb der Hostanwendung aus, wie z. B. das Navigieren zu einer Seite, das Öffnen eines Dialogfelds, das Erstellen eines Datensatzes in der lokalen Benutzeroberfläche oder das Aktualisieren einer Komponente.
• Nutzung von clientspezifischen Funktionen – Verwenden Sie Geräte- oder Browserfunktionen, auf die über den Server nicht zugegriffen werden kann, z. B. Zugriff auf die Zwischenablage, lokaler Speicher oder Geolokalisierung.

Hinweis:

Clientseitige Tools sind nur für Conversational Agents verfügbar, die über eine Oberfläche bereitgestellt werden, die die clientseitige Toolbehandlung unterstützt, z. B. das UiPath TypeScript SDK oder eine beliebige Oberfläche, die das UiPath Konversationsprotokoll implementiert. Die Oberfläche muss einen Handler für jedes clientseitige Tool registrieren; Tools ohne registrierten Handler geben einen Fehler an den Agent zurück.

Konfigurieren von clientseitigen Tools

So fügen Sie Ihrem Conversational Agent ein clientseitiges Tool hinzu:

1. Wählen Sie im Agent-Designer die Option „Tool hinzufügen“ aus.

2. Wählen Sie die Kategorie Client-seitige Tools aus.

3. Füllen Sie folgende Felder aus:

   • Toolname – Ein eindeutiger Name für das Tool. Muss mit einem Buchstaben oder Unterstrich beginnen und darf nur Buchstaben, Ziffern, Leerzeichen und Unterstriche enthalten.
   • Beschreibung – Beschreiben Sie, was das Tool tut und wann es verwendet werden soll. Diese Beschreibung leitet die Entscheidung des Agents, das Tool aufzurufen, ab.
   • Eingabeschema – Ein JSON-Schemaobjekt, das die Parameter definiert, die der Agent beim Aufrufen des Tools an den Client übergibt.
   • Ausgabeschema – Ein JSON-Schemaobjekt, das die Struktur des Ergebnisses definiert, das der Client an den Agent zurückgibt.

   

4. Wählen Sie Erstellen.

Nach dem Erstellen des Tools können Sie zusätzliche Einstellungen im Eigenschaftenbereich des Tools konfigurieren:

• Bearbeiten Sie den Namen des Tools, die Beschreibung und die Schemas.
• Wenden Sie Leitplanken an, um Runtime-Richtlinien zu erzwingen.
• Aktivieren Sie Bestätigungen für Toolaufrufe, um vor der Ausführung die Benutzergenehmigung zu erfordern.

Eingabe- und Ausgabeschemas

Beide Schemas sind erforderlich und müssen gültige JSON Schema-Objekte sein. Sie definieren den Vertrag zwischen dem Agent und dem Kunden:

• Das Eingabeschema gibt an, welche Daten der Agent an den Client sendet, wenn er das Tool aufruft. Der Agent füllt die Eingabewerte basierend auf dem Konversationskontext und der Schemadefinition aus.
• Das Ausgabeschema gibt an, welche Daten der Client nach der Ausführung des Tools an den Agent zurückgibt. Der Agent verwendet dieses Ergebnis, um seine Argumentation fortzusetzen.

Beispielschemas

Für ein Tool, das Aufgaben aus einem Projektboard liest:

Eingabeschema:

{
  "type": "object",
  "properties": {
    "boardId": {
      "type": "string",
      "description": "The ID of the task board to read from"
    },
    "status": {
      "type": "string",
      "enum": ["todo", "in-progress", "done"],
      "description": "Filter tasks by status"
    }
  },
  "required": ["boardId"]
}

Ausgabeschema:

{
  "type": "object",
  "properties": {
    "tasks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "status": { "type": "string" },
          "assignee": { "type": "string" }
        }
      }
    }
  }
}

Verhalten bei vorgefertigten Oberflächen

Auf vorgefertigten Oberflächen wie Instanzverwaltung und iFrame-Einbettung zeigen clientseitige Tools dem Benutzer ein Formular basierend auf dem Ausgabeschema an. Der Benutzer füllt die Felder manuell aus und übermittelt das Ergebnis zurück an den Agent.

Der volle Wert der clientseitigen Tools wird auf benutzerdefinierten Oberflächen erkannt, die mit dem UiPath TypeScript SDK erstellt wurden, wobei die Hostanwendung Toolaufrufe programmgesteuert verarbeitet – Daten lesen, Aktionen auslösen oder mit lokalen Systemen ohne manuelle Benutzereingabe interagieren.

So funktionieren clientseitige Tools zur Runtime

Wenn der Agent während eines Gesprächs ein clientseitiges Tool aufruft:

1. Der Agent entscheidet, dass das Tool basierend auf dem Konversationskontext und der Toolbeschreibung verwendet wird.
2. Wenn Bestätigungen für Toolaufrufe aktiviert sind, überprüft und genehmigt der Benutzer die vorgeschlagene Eingabe, bevor das Tool fortfährt.
3. Die Runtime sendet den Toolaufruf – einschließlich des Toolnamens, der Eingabewerte und der Eingabe-/Ausgabeschemata – an die Clientoberfläche.
4. Die Clientoberfläche führt ihren registrierten Handler für das Tool mithilfe der bereitgestellten Eingabe aus.
5. Der Client gibt das Ergebnis an die Runtime zurück.
6. Der Agent erhält das Ergebnis und setzt seine Argumentation fort.

Bestätigungen von Tool-Aufrufen

Sie können eine Bestätigung durch den Benutzer anfordern, bevor ein clientseitiges Tool ausgeführt wird. Dies ist nützlich für Tools, die Aktionen mit sichtbaren Nebenwirkungen ausführen, z. B. das Erstellen einer Aufgabe, das Aktualisieren eines Datensatzes oder das Navigieren von der aktuellen Seite.

Um die Bestätigung für ein clientseitiges Tool zu aktivieren:

1. Wählen Sie das clientseitige Tool im Agent-Designer aus.
2. Aktivieren Sie in den Tooleigenschaften die Option Bestätigung erfordern.

Wenn diese Option aktiviert ist, hält der Agent an, bevor er das Tool ausführt, und zeigt dem Benutzer die vorgeschlagenen Eingabeparameter an. Der Benutzer kann die Eingaben genehmigen, ändern oder den Toolaufruf ablehnen.

Beispiel: Projektplanungsassistent

Stellen Sie sich einen Projektplanungsassistenten vor, der in eine Aufgabenverwaltungsanwendung eingebettet ist. Der Agent verfügt über zwei clientseitige Tools:

• lesen_board_tasks – Liest die aktuellen Aufgaben aus dem Aufgabenboard des Benutzers in der Hostanwendung.
• create_task – Erstellt eine neue Aufgabe im Board des Benutzers.

Lesen von Daten aus dem Client: Wenn ein Benutzer fragt „Wie soll ich als nächstes arbeiten?“, ruft der Agent read_board_tasks auf. Die Hostanwendung liest den Board-Status und gibt die Aufgabendaten zurück. Der Agent analysiert dann die Aufgaben und schlägt eine Prioritätsreihenfolge basierend auf Status, Fristen und Abhängigkeiten vor.

Schreiben von Daten an den Client: Wenn der Benutzer fragt: „Fügen Sie eine Aufgabe hinzu, um den Q3-Bericht bis Freitag zu überprüfen“, ruft der Agent create_task mit dem Titel, der Beschreibung und dem Fälligkeitsdatum auf. Wenn die Bestätigung aktiviert ist, überprüft der Benutzer zuerst die vorgeschlagenen Aufgabendetails. Die Hostanwendung erstellt die Aufgabe auf dem Board und der Agent bestätigt, dass sie erstellt wurde.

Einschränkungen

• Die Ausführung des clientseitigen Tools hängt von der Verfügbarkeit und Reaktionsfähigkeit der Clientoberfläche ab. Wenn der Client während der Toolausführung die Verbindung trennt, kann der Toolaufruf fehlschlagen.
• Die Clientoberfläche muss einen Handler für jedes clientseitige Tool registrieren, das der Agent definiert. Wenn ein Handler fehlt, gibt der Toolaufruf einen Fehler an den Agent zurück.