Function Calling

Das Function-Calling-System ermöglicht es KI-Assistenzmodellen (z. B. auf Basis von OpenAI), externe APIs aufzurufen, um Aktionen auszuführen oder Daten abzurufen. Eine „Function“ beschreibt dabei eine ausführbare Aktion, die das Modell im Rahmen einer Konversation semantisch anstoßen kann.

Beispiele:

„Erstelle ein neues Jira-Ticket“
„Hole das aktuelle Wetter für Berlin“
„Füge einen Datensatz in einem CRM hinzu“

Jede Funktion wird über eine Funktionsdefinition im System konfiguriert und über eine definierte API-Verbindung (Connection) an eine externe API angebunden.

Aufbau einer Funktion

Beim Erstellen oder Bearbeiten einer Funktion werden folgende Elemente definiert:

Function Name

Ein eindeutiger und beschreibender Funktionsname. Beispiel:

create_jira_ticket

Function Beschreibung

Eine kurze Beschreibung, was die Funktion macht und wann sie verwendet werden soll. Beispiel:

Erstellt ein neues Jira-Ticket im angegebenen Projekt. Gibt im Fehlerfall die API-Fehlermeldung an den Benutzer zurück.

JSON Definition

Die JSON-Definition beschreibt die Eingabeparameter, die das Modell liefern muss, und – bei schreibenden Operationen – ein Body-Template (http_request_body), das verwendet wird, um die tatsächliche HTTP-Anfrage zu konstruieren.

Bestandteile:

parameters: JSON-Schema der erwarteten Eingabeparameter
required: Pflichtfelder
http_request_body: Template für POST/PUT/PATCH-Requests mit Platzhaltern ($parametername)

Beispiel:

{
  "strict": false,
  "parameters": {
    "type": "object",
    "required": ["summary", "project_key", "issue_type"],
    "properties": {
      "summary": {
        "type": "string",
        "description": "Kurztitel des Tickets"
      },
      "project_key": {
        "type": "string",
        "description": "Projekt-Key (z. B. BGPT)"
      },
      "issue_type": {
        "type": "string",
        "description": "Userstory"
      },
      "description": {
        "type": "string",
        "description": "Detaillierte Beschreibung"
      }
    },
    "additionalProperties": false
  },
  "http_request_body": {
    "fields": {
      "project": { "key": "$project_key" },
      "summary": "$summary",
      "issuetype": { "name": "$issue_type" },
      "description": "$description"
    }
  }
}

Parameter Hinweise

Bitte beachten Sie, dass für den http_request_bodykeine dynamischen Parameter oder Arrays unterstützt werden.

API-Verbindung (Connection)

Jede Funktion ist mit genau einer API-Verbindung verknüpft.

Eine Verbindung definiert:

API Endpoint (Request-URL) → z. B. https://jira.example.com/rest/api/2/issue
HTTP-Methode (GET, POST, PUT, PATCH)
Authentifizierungstyp (API Key, Basic Auth, OAuth usw.)
Zugangsdaten

Die Authentifizierung wird automatisch in den Request-Header eingefügt. Diese Daten sind nicht Teil der JSON-Definition.

Ablauf eines Function Calls

Das KI-Modell entscheidet, eine Funktion aufzurufen, z. B.:

{
  "name": "create_jira_ticket",
  "arguments": {
    "summary": "Login-Fehler beheben",
    "project_key": "KEY",
    "issue_type": "Bug",
    "description": "Nutzer können sich nicht einloggen."
  }
}

Das Backend:
liest die Funktionsdefinition aus,
ersetzt Platzhalter ($summary, $project_key, …) im http_request_body,
erstellt die HTTP-Anfrage entsprechend der hinterlegten Verbindung.
Die Anfrage wird ausgeführt, z. B.:

POST https://jira.example.com/rest/api/2/issue
Content-Type: application/json
Authorization: Basic <token>

{
  "fields": {
    "project": { "key": "KEY" },
    "summary": "Login-Fehler beheben",
    "issuetype": { "name": "Bug" },
    "description": "Nutzer können sich nicht einloggen."
  }
}

Die externe API antwortet (z. B. mit JSON). Das System gibt diese Antwort unverändert an das KI-Modell zurück.

5. Request-Typen

Typ	Zweck	`http_request_body` erforderlich?
`GET`	Lesen von Daten	❌ Nein
`POST`	Erstellen neuer Ressourcen	✅ Ja
`PUT`	Aktualisieren bestehender Ressourcen	✅ Ja
`PATCH`	Teilweise Aktualisierung	✅ Ja

6. Beispiel: GET Request

{
  "parameters": {
    "type": "object",
    "required": ["city"],
    "properties": {
      "city": {
        "type": "string",
        "description": "Name der Stadt"
      },
      "units": {
        "type": "string",
        "description": "Temperatureinheit",
        "enum": ["metric", "imperial"]
      }
    },
    "additionalProperties": false
  }
}

Beispiel-Aufruf:

{
  "name": "get_weather",
  "arguments": { "city": "Berlin", "units": "metric" }
}

Ergebnis:

GET https://api.open-meteo.com/v1/forecast?city=Berlin&units=metric

Integrationsleitfaden für API-Anbieter

Um sicherzustellen, dass eine API von einem KI-Assistenten über Function Calling angesprochen werden kann, müssen die nachfolgenden Bedingungen und Voraussetzungen erfüllt sein.

1. Ziel

Damit eine API kompatibel ist, muss sie:

Über HTTP erreichbar sein (GET, POST, PUT, PATCH).
JSON als Eingabe- und Ausgabeformat unterstützen.
Klar definierte Felder und erwartete Datentypen besitzen.
Eindeutige Parameterbezeichnungen bereitstellen, die im Function-JSON referenziert werden können.

2. Anforderungen an den Endpoint

Aspekt	Beschreibung
HTTP-Methoden	Unterstützt `GET`, `POST`, `PUT` oder `PATCH`
Authentifizierung	Wird über die Connection des Systems hinzugefügt (nicht durch den Aufrufer)
Content-Type	`application/json`
Antwortformat	JSON (empfohlen)
Fehlerbehandlung	HTTP-Statuscodes (z. B. `4xx`, `5xx`) und Fehlermeldung als Text oder JSON

3. Parameterstruktur

Die API sollte so gestaltet sein, dass die Felder aus der Function-Definition direkt befüllt werden können.

Beispiel:

{
  "parameters": {
    "type": "object",
    "required": ["customer_id", "status"],
    "properties": {
      "customer_id": {
        "type": "string",
        "description": "Eindeutige Kunden-ID"
      },
      "status": {
        "type": "string",
        "description": "Neuer Status (z. B. active/inactive)"
      }
    }
  },
  "http_request_body": {
    "customer": { "id": "$customer_id" },
    "status": "$status"
  }
}

Business GPT ersetzt die Platzhalter mit den tatsächlichen Werten:

{
  "customer": { "id": "C123" },
  "status": "active"
}

4. Antwortstruktur

Die API sollte eine sinnvolle, strukturierte Antwort zurückgeben, z. B.:

{
  "status": "success",
  "ticket_id": "Project-1234",
  "message": "Ticket created successfully"
}

Fehler sollten standardisiert werden, z. B.:

{
  "status": "error",
  "message": "Invalid project key"
}

5. Best Practices

Verwenden Sie sprechende Parameternamen, die mit der Business-Logik korrespondieren.
Definieren Sie alle Pflichtfelder im JSON-Schema (required).
Halten Sie sich an das Prinzip: „LLM liefert nur die semantischen Werte, nicht das Request-Format.“
Nutzen Sie Platzhalter ($parameter) konsistent im http_request_body.

6. Beispiel einer vollständigen Integration

Ziel:

Eine API, die ein Support-Ticket anlegt.

Function JSON:

{
  "parameters": {
    "type": "object",
    "required": ["title", "priority"],
    "properties": {
      "title": { "type": "string", "description": "Titel des Tickets" },
      "priority": { "type": "string", "enum": ["Low", "Medium", "High"] },
      "description": { "type": "string" }
    }
  },
  "http_request_body": {
    "ticket": {
      "title": "$title",
      "priority": "$priority",
      "description": "$description"
    }
  }
}

Business GPT generiert:

POST https://api.supportsystem.com/v1/tickets
Authorization: Bearer <token>
Content-Type: application/json

{
  "ticket": {
    "title": "Zugangsdaten verloren",
    "priority": "High",
    "description": "Der Benutzer kann sich nicht anmelden."
  }
}

API antwortet:

{
  "status": "success",
  "ticket_id": "SUP-9876"
}

7. Zusammenfassung

Komponente	Verantwortung
KI-Modell	Liefert Funktionsname + Parameterwerte
Backend	Ersetzt Platzhalter, führt HTTP-Request aus, fügt Authentifizierung hinzu
Externe API	Nimmt JSON entgegen, verarbeitet es, liefert Antwort zurück
LLM	Nutzt die Antwort, um dem Benutzer die Aktion oder das Ergebnis mitzuteilen