API

Eigene Tools

Lass die KI mitten im Gespräch deine API aufrufen

Überblick

Ein eigenes Tool ist ein Endpoint von dir, den der Agent aufrufen kann, während er mit einem Kunden spricht: einen Kredit per Ausweisnummer abfragen, den Lagerbestand prüfen, ein Ticket eröffnen. Du beschreibst, wann es greift und welche Parameter es braucht; die KI entscheidet, wann sie es aufruft, füllt die Parameter mit dem, was der Kunde gesagt hat, und antwortet mit dem, was deine API zurückgegeben hat. Bis zu 15 Tools pro Agent.

Definition

Jedes Tool ist ein Eintrag mit diesen Feldern:

`name`	Technischer Name, mit dem die KI es aufruft: Buchstaben, Zahlen und Unterstrich (consultar_credito).
`description`	Wann es zu nutzen ist und was es zurückgibt. Das liest die KI, um zu entscheiden; formuliere es als Anweisung („Fragt einen Kredit per Ausweisnummer ab; gibt Saldo und Raten zurück“).
`parameters`	Liste aus {name, type (string \| number \| boolean \| enum), description, required, enum_values}. Die KI füllt sie mit dem, was der Kunde gesagt hat.
`method + endpoint`	GET, POST, PUT oder DELETE und die vollständige URL.
`auth`	NONE, BEARER (Authorization: Bearer <token>), API_KEY (Header-Name und -Wert, die du wählst) oder BASIC (Benutzername und Passwort).
`headers`	Zusätzliche Header, die bei jedem Aufruf mitgehen.
`body_template`	Optionale JSON-Vorlage mit {{param}}. Ohne sie schicken POST/PUT die Parameter als JSON-Objekt.
`response_path`	Optionaler Pfad mit Punkten (data.results) zu dem Teil der Antwort, den die KI lesen soll.

So läuft der Aufruf ab

GET und DELETE hängen die Parameter als Query-String an die URL. POST und PUT schicken sie als JSON-Body: oder das ausgefüllte body_template. Die Auth-Header und die zusätzlichen Header gehen bei jedem Aufruf mit. Antworte mit 2xx und JSON: Die KI bekommt den Body (oder den Teil aus response_path) als Text und antwortet damit. Ein Code außer 2xx kommt bei der KI als „API returned <status>“ an, und sie sagt dem Kunden, dass die Abfrage nicht geklappt hat; es gibt keine Wiederholungsversuche.

So erstellst du eins

Canvas (newui.tbit.app): Frag „Welche eigenen Tools habe ich?“ → die Liste hat „Neues Tool…“; jede Zeile öffnet das Tool mit Bearbeiten. Ein Formular fragt alles oben Genannte ab; Secrets, die du beim Bearbeiten leer lässt, bleiben erhalten.
MCP (Claude, ChatGPT…): list_custom_tools zum Lesen, manage_custom_tool mit action=create | update | delete. Die Änderung wird vorgeschlagen und du bestätigst sie.
App der Plattform: Integrationen → Eigene API.

Beispiel: Erstellen über den MCP

json

manage_custom_tool
{
  "action": "create",
  "name": "consultar_credito",
  "description": "Consulta el estado de un crédito por número de cédula; devuelve saldo, cuotas pendientes y próxima fecha de pago.",
  "method": "GET",
  "endpoint": "https://api.tunegocio.com/v1/creditos",
  "parameters": [
    { "name": "cedula", "type": "string", "description": "Cédula del cliente, solo dígitos", "required": true }
  ],
  "auth_type": "BEARER",
  "auth_token": "<tu token>",
  "response_path": "data"
}

Was dein Endpoint bekommt

Mit dem Beispiel oben ruft die KI Folgendes auf, wenn ein Kunde nach seinem Kredit fragt:

http

GET https://api.tunegocio.com/v1/creditos?cedula=1032456789
Authorization: Bearer <tu token>
Accept: application/json

→ 200 { "data": { "saldo": 1250000, "cuotas_pendientes": 3, "proximo_pago": "2026-10-05" } }

Best Practices

Schreib die Beschreibung für die KI, nicht für Entwickler: wann es zu nutzen ist und was zurückkommt.
Markiere nur als Pflicht, was die KI beim Kunden erfragen muss; für alles andere setzt du auf deiner Seite einen Standardwert.
Halte GETs idempotent: Die KI kann dasselbe Tool in einem Gespräch zweimal aufrufen, wenn der erste Versuch fehlgeschlagen ist.
Gib kleines, flaches JSON zurück. Nutze response_path, wenn deine API die Ergebnisse verpackt.