# Beispiele für API-Tools

Hier finden Sie Beispiele für benutzerdefinierte API-Tools, die von aiStudio-Agenten eingesetzt werden können. Die Beispiele zeigen, wie externe Datenquellen und Services effektiv in intelligente Assistenten integriert werden – sei es zur Tarifberechnung, Informationsabfrage oder für branchenspezifische Anwendungen.

Einige der Beispiele können Sie direkt übernehmen: Klicken Sie auf das Symbol ℹ️, um die Konfigurationen für das Tool sowie für den Agenten (Prompt und Trigger) anzuzeigen.

# Stromtarifrechner

Der Stromtarifrechner ist ein Tool zur Berechnung der Kosten verschiedener Stromtarife auf Basis des Verbrauchs. Es kann z. B. in einem Custom-Agenten "Stromtarifberater", dem Tarifinformationen und Entscheidungskriterien vorliegen, eingesetzt werden. Nutzer:innen geben ihren geschätzten Stromverbrauch, die Postleitzahl (für die Prüfung des Liefergebiets) und den gewünschten Tariftyp ein – der Custom-Agent nutzt dieses Tool, um dynamisch die jeweiligen Kosten des gewählten Tarifs zu bestimmen und auszugeben.

Verwendete API: durch Kauz erstellter HTTP-Endpunkt via Node-RED (https://node-red.kauz.io/rechner)
Request-Typ: GET
Authentifizierung: Basic Auth

# Anlage des Tools

ℹ️ Tool-Konfiguration: Stromtarifrechner

Request-Parameter und Placeholder-Konfiguration:

Schlüssel	Placeholder	Beschreibung
`verbrauch`	`$verbrauch`	Der geschätzte Verbrauch, den der Nutzer angibt
`plz`	`$plz`	Die Postleitzahl (PLZ), die der Nutzer angibt
`tarif`	`$tarif`	Der vom Nutzer gewählte Tarif ("basis", "komfort" oder "flex")

Authentifizierung:

Zur Authentifizierung wird Basic Auth verwendet. Dabei werden der Benutzername kauz und das entsprechende Passwort genutzt.

# Nutzung im Agenten

ℹ️ Agent-Konfiguration: Stromtarifberater

Trigger: Der Nutzer sucht einen Stromtarif.

Prompt: Du ermittelst den besten Strompreis für den Nutzer.
Stelle dem Nutzer nacheinander verschiedene Fragen (z. B. zur Preisgarantie), die sich aus den Daten ergeben, um den passenden Strom-Tarif zu finden. Stelle immer nur eine Frage einzeln und lasse den Nutzer darauf antworten und erst danach stellst du die nächste Frage.
Wenn der Nutzer nach den Kosten eines Tarifs fragt berechnet du die jährlichen Kosten mit dem Stromtarifrechner. Wenn die Response des Stromtarifrechners invalid ist oder der Nutzer die eine andere PLZ als 40223 angibt, dann informiere den Nutzer, dass nur Wohngebiete im PLZ-Bereich 40223 mit Strom beliefert werden können.
Verwende die folgenden Daten: {data}

(Der Custom-Agent verfügt als Datengrundlage über eine strukturierte Übersicht über die vorhandenen Tarife.)

# Beispielhafter Konversationsverlauf

# Zählerstand melden

Das Tool dient der Meldung des Zählerstands durch den Nutzer. Es wird durch einen Data Collection Agent "Zählerstandserfassung" aufgerufen. Der Agent fragt nacheinander die Vertragsnummer und den Zählerstand ab. Nach vollständiger Erfassung werden die Daten automatisch übermittelt.

Verwendete API: durch Kauz erstellter HTTP-Endpunkt via Node-RED (https://node-red.kauz.io/zaehlerstandmeldung)
Request-Typ: POST
Authentifizierung: Basic Auth

# Anlage des Tools

ℹ️ Tool-Konfiguration: Zählerstand melden

Request-Parameter und Placeholder-Konfiguration:

Schlüssel	Placeholder	Beschreibung
`vertragsnummer`	$vertragsnummer	Vom Nutzer angegebene Vertragsnummer
`zaehlerstand`	$zaehlerstand	Vom Nutzer gemeldeter Zählerstand

Body-Konfiguration (JSON):

{
    "zaehlerstand": "$zaehlerstand",
    "vertragsnummer": "$vertragsnummer"
}

# Nutzung im Agenten

ℹ️ Agent-Konfiguration: Zählerstand melden

Trigger: Der Nutzer möchte seinen Zählerstand melden.

Prompt: Erstelle eine Entscheidungslogik für einen Chatbot, der Daten des Nutzers erfragen will.
Die benötigten Daten sind folgende: Der Chatbot fragt die benötigten Informationen der Reihe nach ab. Er prüft, ob die erhaltene Information ein valider Wert ist. Wenn der Wert valide ist, bedankt er sich und geht zur nächsten Frage über. Wenn er nicht valide ist, es sich aber nur um einen Fehler handeln könnte, sagt er, dass ihm dieser Wert unplausibel erscheint und bittet um eine Überprüfung der Eingabe. Wenn der Nutzer eine Rückfrage stellt, beantwortet er die Rückfrage und fragt dann, ob er nun die gewünschte Information eingeben möchte. Wenn der Nutzer sagt, dass er sich geirrt hat oder seine Angabe ändern möchte, lässt der Chatbot ihn seine Information erneut eingeben. Wenn der Nutzer etwas fragt oder sagt, das gar nichts mit dem Thema zu tun hat, antwortet der Chatbot, dass er nur dazu da ist, die gewünschten Informationen zu erheben. Mit allen anderen Fragen möge sich der Nutzer an jemand anderes wenden. Der Chatbot prüft nach jedem Schritt, ob er alle Informationen abgefragt hat. Sobald der Chatbot alle Informationen abgefragt hat, stellt er sie dem Nutzer zusammengefasst vor und nutzt das Tool Zählerstand melden.

# Beispielhafter Konversationsverlauf

# Jobsuche

Das Tool dient der Suche nach Stellenangeboten über die Arbeitsagentur-API und kann mit verschiedenen Agententypen kombiniert werden. Nutzer*innen können nach Jobs in bestimmten Regionen und mit bestimmten Stichworten suchen, woraufhin der Agent relevante Stellenangebote zurückliefert.

Verwendete API: REST-API für Jobsuche der Arbeitsagentur (https://rest.arbeitsagentur.de/jobboerse/jobsuche-service/pc/v4/jobs)
Request-Typ: GET
Authentifizierung: API-Key (X-API-Key)

# Anlage des Tools

ℹ️ Tool-Konfiguration: Jobsuche

Request-Parameter und Placeholder-Konfiguration:

Schlüssel	Placeholder	Beschreibung
`was`	`$was`	Jobtitel, nach dem der User sucht.
`wo`	`$wo`	Der Ort, in dem der Nutzer nach einem Job sucht.

Authentifizierung:

Zur Authentifizierung wird ein API-Key verwendet, der im HTTP-Header unter dem Namen X-API-Key mitgesendet wird.

# Nutzung im Agenten

ℹ️ Agent-Konfiguration: Default-Agent zum Wissensabruf (RAG)

In diesem Fall wird das Tool durch den Default-RAG-Agenten aufgerufen. Bei Bedarf kann definiert werden, in welchen Situationen das Tool aufgerufen werden soll.

# Beispielhafter Konversationsverlauf

# AINewsTool

Dieses Tool dient der Abfrage aktueller KI-Nachrichten über die NewsAPI. Es ermöglicht RAG-Agenten, basierend auf Nutzeranfragen relevante Artikel zu KI-Themen zu finden und strukturiert auszugeben.

Verwendete API: newsapi.org (https://newsapi.org/v2/everything)
Request-Typ: GET
Authentifizierung: API-Key (Query Parameter)

# Anlage des Tools

ℹ️ Tool-Konfiguration: AINewsTool

Request-Parameter und Placeholder-Konfiguration:

Schlüssel	Placeholder	Beschreibung
`q`	`$query`	Anfrage des Nutzers (z.B. "KI, LLM").
`language`	`$language`	Die gewünschte Sprache der Antwort (z.B. "de" oder "en").
`domains`		Die Webseiten, von denen die Artikel stammen sollen. (Die Quellen, die von newsapi.org unterstützt werden (siehe API-Dokumentation)).

Authentifizierung:

Die Authentifizierung erfolgt mittels API-Key, der als Query-Parameter "apiKey" übergeben wird. Der Schlüsselwert bleibt geschützt und wird automatisch in jede Anfrage eingefügt.

# Nutzung im Agenten

ℹ️ Agent-Konfiguration: AINews

Trigger: Der Nutzer interessiert sich über die letzten Neuigkeiten/Artikel/Nachrichten über KI oder LLMs.

Prompt: Du bist ein professioneller KI-Nachrichtenagent. Deine Aufgabe ist es, dem Nutzer eine Liste der wichtigsten und relevantesten Neuigkeiten und Artikel aus dem Bereich der Künstlichen Intelligenz bereitzustellen. Nutze dafür das dir zur Verfügung stehende Tool. WICHTIG: Verwende ausschließlich die Artikel, die du über newsAPI mit dem Tool bekommen hast. Erfinde keine neuen Überschriften, Quellen oder Links. Präsentiere dem Nutzer die gefundenen Artikel im folgenden Format:

Ressource: www.example.com
Titel: Mustertitel
Kurze Zusammenfassung: (höchstens 4 Sätze)
Link: URL des Artikels

Du stellst jeweils eine Liste mit 5 Artikeln zur Verfügung. Falls der Nutzer weitere Artikel wünscht, gib ihm eine neue Liste mit 5 weiteren Artikeln usw.