Client-Funktionstools

Wenn Sie Funktionen haben, auf die über Ihren Clientcode, aber nicht über gehostete Tools wie OpenAPI oder MCP zugegriffen werden kann, können Sie Clientfunktions-Tools verwenden. Clientseitige Funktions-Tools werden immer auf dem Client und nicht vom Agent ausgeführt.

Funktionsweise

Wenn ein Agent ein Clientfunktions-Tool auslöst, geschieht Folgendes:

  1. Sitzungsblockierung: Die Unterhaltungssitzung wird serverseitig „blockiert“.
  2. Clientausführung: Ihre Clientanwendung muss den Tool-Aufruf identifizieren und die entsprechende Logik in Ihrer lokalen Umgebung ausführen.
  3. Antwort senden: Nach Abschluss der Ausführung muss Ihre Clientanwendung die Antwort mithilfe der toolResponses-Felder an den Agent zurückgeben.

Der Agent wartet auf diese Antwort, bevor er mit der Unterhaltung fortfährt.

Konfiguration

Wenn Sie ein Clientfunktions-Tool erstellen, definieren Sie, wie der Agent Ihren clientseitigen Code versteht und mit ihm interagiert:

  • Name: Eine eindeutige Kennung für das Tool (z. B. open_settings).
  • Beschreibung: Eine kurze Beschreibung des Zwecks des Tools. Agent-Modelle verwenden diese Beschreibung, um zu entscheiden, wann die Funktion aufgerufen werden soll.
  • Ein-/Ausgabe-Schema: Im OpenAPI-Format definiert. Dadurch wird die Struktur der Daten festgelegt, die der Agent sendet und empfängt.

Anwendungsfälle

Clientfunktions-Tools eignen sich besonders für:

  • UI-/UX-Aktionen: Änderungen an der Benutzeroberfläche Ihrer Anwendung auslösen (z. B. „Zum Supportbildschirm wechseln“).
  • Lokale Gerätedaten: Zugriff auf Informationen, die nur im Kontext der App verfügbar sind (z. B. „Aktuellen Akkustand abrufen“).
  • Private APIs: Integration in Dienste, die nur über die Clientumgebung erreichbar sind.

Beispiel

Das folgende Beispiel ist eine Sitzungsantwort, die angibt, dass die Clientanwendung eine Funktion aufrufen soll:

"outputs": [
  {
    "toolCalls": {
      "toolCalls": [
        {
          "id": "<execution id>",
          "tool": "<client function tool's resource name>",
          "args": {
            "zip_code": "92031"
          },
          "displayName": "get_nearest_store"
        }
      ]
    },
    "turnCompleted": true,
  }
]

Im folgenden Beispiel wird eine nachfolgende Sitzung mit der an die Anfrage angehängten Toolausgabe ausgeführt. Die Clientanwendung muss diese Felder ausfüllen und dieselben Werte für id, tool und display_name wie in der vorherigen Nachricht verwenden.

"inputs": [
  {
    "toolResponses": {
      "toolResponses": [
        {
          "displayName": "get_nearest_store",
          "id": "<execution id>",
          "tool": "<client function tool's resource name>",
          "response": {
            "name": "Alibaba",
            "address": "43 Alpha Road, Mountain View, CA 92039, USA"
          },
        }
      ]
    }
  }
]