Actions and API Integration

Was sind Actions?

Actions erweitern Custom GPTs um die Fähigkeit, mit externen APIs zu interagieren. Während ein Standard-Custom-GPT nur auf sein Training und hochgeladene Dateien zugreifen kann, ermöglichen Actions dem GPT:

• Echtzeit-Daten abzurufen – Wetter, Aktienkurse, News, etc.

• Externe Services zu nutzen – Datenbanken, Cloud-Speicher, Business-Tools

• Aktionen auszuführen – E-Mails senden, Kalendereinträge erstellen, Bestellungen aufgeben

• Dynamische Inhalte zu generieren – Aktuelle Informationen statt statisches Wissen

Wie funktionieren Actions?

Actions basieren auf dem OpenAPI-Standard (früher Swagger). Der Prozess läuft in fünf Schritten ab:

Der Action-Workflow

1. User stellt eine Frage – z.B. "Erzähl mir einen Chuck Norris Witz"

2. GPT analysiert die Anfrage – Erkennt: Dafür brauche ich die Chuck Norris API

3. GPT macht API-Call – Sendet HTTP-Request an api.chucknorris.io

4. API antwortet mit Daten – JSON mit einem zufälligen Witz

5. GPT verarbeitet die Antwort – Formuliert sie nutzerfreundlich

---

Anatomie einer Action

Eine Action besteht aus drei Komponenten:

1. OpenAPI Schema (JSON)

Das Schema definiert, wie die API funktioniert:

{
  "openapi": "3.1.0",
  "info": {
    "title": "Chuck Norris Jokes API",
    "description": "Holt zufällige Chuck Norris Witze",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.chucknorris.io"
    }
  ],
  "paths": {
    "/jokes/random": {
      "get": {
        "description": "Gibt einen zufälligen Chuck Norris Witz zurück",
        "operationId": "getRandomJoke",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Erfolgreicher API-Call",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "value": {
                      "type": "string",
                      "description": "Der Witz-Text"
                    },
                    "id": {
                      "type": "string",
                      "description": "Eindeutige ID des Witzes"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

2. Authentication (falls nötig)

Viele APIs benötigen einen API-Key. ChatGPT unterstützt drei Authentifizierungsmethoden:

Methode	Beschreibung	Beispiel
API Key	Key wird im Header oder Query-Parameter mitgesendet	Authorization: Bearer YOUR_KEY
OAuth	User autorisiert den GPT, in seinem Namen zu handeln	Google, GitHub, Zapier
None	Öffentliche APIs ohne Authentifizierung	Chuck Norris API, Cat Facts API

Die Chuck Norris API benötigt keine Authentifizierung – sie ist öffentlich zugänglich.

3. Instructions (Optional)

Du kannst dem GPT Anweisungen geben, wann und wie er die Action nutzen soll:

Wenn der User nach einem Chuck Norris Witz fragt:
1. Nutze die getRandomJoke Action
2. Präsentiere den Witz in Anführungszeichen
3. Füge am Ende hinzu: "💪 Chuck Norris approved!"

---

Actions erstellen: Schritt für Schritt

Schritt 1: API-Dokumentation lesen

Bevor du eine Action erstellst, musst du verstehen, wie die API funktioniert:

• Endpoint – https://api.chucknorris.io/jokes/random

• HTTP-Methode – GET

• Parameter – Keine (für random joke)

• Response-Format – JSON mit value, id, url, etc.

Tipp: Die meisten APIs haben eine Dokumentation. Für Chuck Norris API: https://api.chucknorris.io/

Schritt 2: OpenAPI-Schema erstellen

Du hast drei Möglichkeiten:

Option A: Manuell schreiben

{
  "openapi": "3.1.0",
  "info": { ... },
  "servers": [ ... ],
  "paths": { ... }
}

Option B: Von URL importieren Wenn die API ein OpenAPI-Schema bereitstellt, kannst du es direkt importieren:

https://api.example.com/openapi.json

Option C: ChatGPT fragen Beschreibe die API und lass ChatGPT das Schema generieren:

Erstelle ein OpenAPI 3.1.0 Schema für die Chuck Norris API.
Endpoint: GET https://api.chucknorris.io/jokes/random
Response: JSON mit "value" (string) und "id" (string)

Schritt 3: Action im GPT Builder hinzufügen

1. Gehe zu ChatGPT → Explore GPTs → Create a GPT

2. Wechsle zum Configure-Tab

3. Scrolle zu Actions → Create new action

4. Füge dein OpenAPI-Schema ein

5. Teste die Action mit Test

6. Speichere den GPT

Schritt 4: Testen

Stelle Fragen, die die Action triggern sollten:

• ✅ "Tell me a Chuck Norris joke"

• ✅ "I need a random Chuck Norris fact"

• ✅ "Entertain me with Chuck Norris wisdom"

Beobachte im Chat, ob der GPT die Action aufruft (du siehst eine Meldung wie "Used getRandomJoke").

---

Erweiterte Konzepte

Query-Parameter

Manche APIs akzeptieren Parameter. Die Chuck Norris API unterstützt z.B. Kategorien:

GET https://api.chucknorris.io/jokes/random?category=dev

OpenAPI-Schema mit Parameter:

"parameters": [
  {
    "name": "category",
    "in": "query",
    "description": "Filter nach Kategorie (z.B. dev, movie, food)",
    "required": false,
    "schema": {
      "type": "string"
    }
  }
]

POST-Requests

Für APIs, die Daten empfangen (z.B. Formular-Submissions):

"post": {
  "description": "Sendet Feedback an die API",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "message": { "type": "string" },
            "rating": { "type": "integer" }
          }
        }
      }
    }
  }
}

Fehlerbehandlung

Definiere, wie der GPT auf Fehler reagieren soll:

"responses": {
  "404": {
    "description": "Witz nicht gefunden"
  },
  "500": {
    "description": "Server-Fehler"
  }
}

---

Best Practices

1. Beschreibungen sind kritisch

Der GPT entscheidet anhand der description-Felder, ob und wann er eine Action nutzt. Schreibe klare, präzise Beschreibungen:

❌ Schlecht: "description": "Gets data" ✅ Gut: "description": "Ruft einen zufälligen Chuck Norris Witz von der API ab"

2. Teste verschiedene Formulierungen

Der GPT muss erkennen, wann die Action relevant ist. Teste mit verschiedenen Phrasierungen:

• "Give me a Chuck Norris joke"

• "Tell me something funny about Chuck Norris"

• "Random Chuck Norris fact"

3. Rate Limits beachten

Manche APIs haben Nutzungslimits. Informiere den User:

Hinweis: Diese API erlaubt 100 Anfragen pro Stunde. Bei intensiver Nutzung
kann es zu Verzögerungen kommen.

4. Datenschutz

Wenn die API persönliche Daten verarbeitet:

• ✅ Informiere User in der GPT-Beschreibung

• ✅ Nutze OAuth statt API-Keys (wenn möglich)

• ✅ Erkläre, welche Daten weitergegeben werden

5. Fallback-Verhalten

Was passiert, wenn die API nicht antwortet?

Wenn die Chuck Norris API nicht verfügbar ist:
- Informiere den User höflich
- Biete alternative Unterhaltung an
- Versuche es NICHT mehrfach automatisch (verhindert Spam)

---

Häufige Fehler und Lösungen

Problem: "Action wird nicht aufgerufen"

Ursachen:

• Beschreibung ist zu vage oder fehlt

• Der User verwendet andere Formulierungen als erwartet

• Der GPT hat die Action nicht als relevant eingestuft

Lösungen:

• Verbessere die description im Schema

• Füge explizite Anweisungen in den Instructions hinzu

• Teste mit direkteren Formulierungen ("Use the getRandomJoke action")

Problem: "API returns 401 Unauthorized"

Ursachen:

• API-Key fehlt oder ist falsch

• Authentifizierungsmethode falsch konfiguriert

Lösungen:

• Überprüfe den API-Key in den Action-Settings

• Stelle sicher, dass die Authentifizierungsmethode korrekt ist (Header vs. Query)

Problem: "Response kann nicht geparst werden"

Ursachen:

• Das OpenAPI-Schema stimmt nicht mit der tatsächlichen API-Response überein

• Die API gibt ein anderes Format zurück als dokumentiert

Lösungen:

• Teste die API manuell (z.B. mit curl oder Postman)

• Vergleiche die echte Response mit dem Schema

• Passe das schema unter responses an

---

Weiterführende Ressourcen

• OpenAI Actions Documentation

• OpenAPI Specification

• Chuck Norris API Docs

• Public APIs Collection

---

Nächste Schritte

• 📝 Exercise: Chuck Norris Joke GPT erstellen

• 🔧 Testing and Refining Your Custom GPT

• 🎯 Step-by-Step Guide to Creating a Custom GPT