Copyright © 2022-2026 basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

// integration

Lesezugriff

Gilt für

Produkt: Cloud · Server · Zielgruppe: Entwickler / Integrator

Werkzeuge entwerfen, die aus einem externen System lesen: suchen, abrufen, auflisten – und Ergebnisse so formen, dass der Assistent sie verlässlich verwenden kann. Gute Lesewerkzeuge sind klein, klar beschrieben und liefern begrenzte, strukturierte, reine Textdaten mit Verweisen auf das Original.

Die drei Grundwerkzeuge

Werkzeug	Zweck	Typische Parameter	Ergebnis
search	Aus einer Frage die passenden Einträge finden	`query`, optional `limit`, Filter (Bereich, Projekt, Zeitraum)	Liste kurzer Treffer: ID, Titel, Auszug, Link
get	Einen bekannten Eintrag vollständig lesen	`id`	Inhalt als Text, Metadaten, Link
list	Einen Bereich überblicken	`parent` oder Filter, `limit`, `cursor`	Seite von Einträgen mit Cursor für die nächste

Mehr braucht ein Konnektor selten. Widerstehen Sie der Versuchung, die gesamte API des Zielsystems als Werkzeuge zu spiegeln – das Modell wählt zwischen wenigen, klaren Werkzeugen besser als zwischen dreißig ähnlichen.

Beschreibungen, die das Modell versteht

Das Sprachmodell entscheidet anhand der Werkzeugbeschreibung, ob und wie es ein Werkzeug aufruft. Schreiben Sie Beschreibungen für dieses Publikum:

Was das Werkzeug liefert und wann es passt: „Sucht Wiki-Seiten nach Stichwörtern. Verwenden, wenn der Nutzer nach internen Anleitungen, Richtlinien oder Prozessen fragt."
Wie Parameter zu füllen sind: „query: 2–5 Stichwörter, keine ganzen Sätze."
Was es nicht tut: „Liefert keine Anhänge; für Dateien get_attachment verwenden."
Parameter mit engem Typ und Standardwert (limit, Standard 10, maximal 20).

Testen Sie Beschreibungen mit echten Nutzerfragen: Ruft das Modell das richtige Werkzeug mit sinnvollen Parametern auf?

Ergebnisse formen

Begrenzen. Jeder Aufruf hat eine Obergrenze an Treffern und an Zeichen je Treffer. Die Websuche etwa liefert höchstens 10 Treffer mit begrenzter Textmenge je Treffer. Große Dokumente kürzen Sie oder liefern sie abschnittsweise mit cursor.

Strukturieren. Ein Treffer hat immer dieselben Felder: id, title, excerpt oder content, url, gegebenenfalls updated_at, author, path. So kann das Modell zitieren und verlinken.

Reiner Text. Entfernen Sie HTML, Skripte, Styles und aktive Inhalte, bevor Text zurückgeht. Markdown ist in Ordnung; eingebettetes HTML nicht. Ergebnisse sind Daten – basebox rahmt sie so ein, Ihre Aufgabe ist, dass sie auch so aussehen.

Verweisen. Jeder Treffer trägt einen stabilen Link ins Zielsystem. basebox öffnet solche Links in einem neuen Tab; Nutzer prüfen damit die Quelle.

Leer ist ein Ergebnis. „Keine Treffer für ‚…' im Bereich ‚…'" ist besser als eine leere Liste – das Modell kann es dem Nutzer erklären und die Frage umformulieren.

Berechtigungen respektieren

Lesewerkzeuge rufen das Zielsystem mit den Zugangsdaten des Nutzers auf. Was das System verweigert, geben Sie als Ergebnis zurück („Kein Zugriff auf Projekt X"); Sie filtern nicht selbst und Sie versuchen es nicht mit einem anderen Konto. Details: Berechtigungen.

Leistung und Robustheit

Timeouts je Aufruf ans Zielsystem (wenige Sekunden); bei Überschreitung ein klarer Fehler statt eines hängenden Werkzeugs – der Nutzer sieht im Chat, wie lange ein Werkzeug schon läuft.
Idempotent: Lesen darf beliebig wiederholt werden; basebox oder das Modell kann einen Aufruf erneut absetzen.
Ratenlimits des Zielsystems als Ergebnis melden (429), nicht wegretryen.
Kein Cache über Nutzer hinweg. Wenn überhaupt, dann nur innerhalb eines Aufrufs.
Parallelität: Mehrere Nutzer gleichzeitig; Ihr Server ist zustandslos.

Beispiel: Treffer-Objekt

{
  "id": "wiki:it:vpn-einrichten",
  "title": "VPN einrichten (Windows)",
  "excerpt": "Schritt 1: Client herunterladen … Schritt 4: Zertifikat importieren.",
  "url": "https://wiki.example.com/doku.php?id=it:vpn-einrichten",
  "updated_at": "2026-05-12"
}

Kurz, zitierbar, verlinkt – und ohne alles, was das Modell nicht braucht.

Was Lesewerkzeuge nicht tun

Sie verändern nichts – keine „gelesen"-Markierungen, keine Zähler, keine Side Effects.
Sie laden nicht das ganze System – keine Volllisten ohne Limit.
Sie rendern keine Webseiten – wo ein Anbieter eine API bietet (wie die Websuche), nutzen Sie sie statt HTML zu scrapen.
Sie liefern keine Anweisungen an das Modell – Inhalte aus dem Zielsystem, die wie Anweisungen aussehen, bleiben Daten. basebox rahmt sie entsprechend ein; helfen Sie, indem Sie nichts umformulieren.

Checkliste

Höchstens eine Handvoll Werkzeuge: search, get, list
Beschreibungen mit Zweck, Einsatzfall, Parameterhinweisen
Treffer- und Zeichenlimits je Aufruf
Einheitliche Felder je Treffer, stabile Links
Reiner Text, kein HTML, keine aktiven Inhalte
Verweigerungen des Zielsystems als Ergebnis
Timeouts, idempotent, zustandslos

Weiter: Schreibzugriff · Beispiele