Integrationsmuster

Die zwei Arten der Anbindung

Die meisten Teams greifen zuerst zur imperativen Variante, weil sie einfacher aussieht:

# Imperative: your code decides, always, on every turn.
context = hive.search(user_question)        # always fires, relevant or not
answer  = llm(prompt=user_question, context=context)
return answer

Die Tool-Calling-Variante überlässt diese Beurteilung dem Modell:

# Tool-based: the model decides whether to search, what to search for,
# and whether what came back was worth a follow-up query.
tools = [
    {
        "name": "search_team_knowledge",
        "description": (
            "Search the team's knowledge base for prior decisions, standards "
            "and meeting outcomes. Use whenever the answer might depend on "
            "something the team already decided. Prefer this over guessing."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "question": {
                    "type": "string",
                    "description": "A natural-language question, not keywords.",
                }
            },
            "required": ["question"],
        },
    },
]
# ... on a tool_use block, call aiqbee_search and return the result.

Warum die zweite gewinnt

1. Die Abrufqualität hängt von der Anfrage ab, und das Modell formuliert bessere Anfragen

aiqbee_search arbeitet semantisch. Mit den rohen Worten des Benutzers liefert es ordentliche Ergebnisse; mit einer gut formulierten Frage deutlich bessere. Das Modell hat die Unterhaltung vor sich – es kann „Haben wir uns dagegen entschieden?“ in „Wie lautete die Entscheidung zur Ratenbegrenzung der öffentlichen API?“ auflösen. Ihr Code kann das nicht, da er nicht weiß, worauf sich „das“ bezog.

2. Die meisten Gesprächsrunden sollten gar nicht suchen

„Danke, das hat funktioniert“ erfordert keinen Abruf. Eine bedingungslose Suche kostet Latenz und schiebt irrelevanten Kontext in den Prompt, was die Antworten nachweislich verschlechtert. Das Modell verzichten zu lassen, ist eine Funktion und keine Faulheit.

3. Eine Suche reicht oft nicht aus

Echte Fragen erfordern eine erste Suche, einen Blick auf das Ergebnis und eine zweite, engere Suche. Diese Schleife ist beim Tool-Calling selbstverständlich und lässt sich in festem Kontrollfluss nur umständlich ausdrücken.

4. Das Zurückschreiben ist der Punkt, an dem sich eine Gedächtnisschicht bezahlt macht

Das ist der Teil, den die meisten Integrationen auslassen, und er ist der ganze Sinn. Geben Sie dem Modell auch ein Schreib-Tool, und Wissen sammelt sich als Nebeneffekt der normalen Arbeit an, statt dass jemand daran denken muss, es abzulegen.

{
    "name": "record_team_knowledge",
    "description": (
        "Record a durable decision, standard or outcome so it is available "
        "to the team later. Use when something is settled that a colleague "
        "would need in six months. Do NOT use for chit-chat, transient "
        "status, or anything you were not told."
    ),
    "input_schema": {
        "type": "object",
        "properties": {
            "title":   {"type": "string"},
            "content": {"type": "string",
                        "description": "Include who, what and WHY. Self-contained."},
            "type_id": {"type": "string",
                        "description": "A real id from aiqbee_get_neuron_types."},
        },
        "required": ["title", "content", "type_id"],
    },
}

Tool-Beschreibungen schreiben, die funktionieren

Die Beschreibung ist Ihre eigentliche Integrationsfläche – sie ist der Prompt, der entscheidet, ob das Tool korrekt verwendet wird. Einige Punkte, die durchgehend wichtig sind:

• Sagen Sie, wann es zu verwenden ist, nicht nur, was es tut. „Durchsucht die Wissensbasis“ führt zu unregelmäßiger Nutzung. „Verwenden, wenn die Antwort von einer früheren Teamentscheidung abhängen könnte“ führt zu guter Nutzung.
• Sagen Sie, wann nicht. Ohne ausdrückliche Ausnahme werden Schreib-Tools bei Höflichkeitsfloskeln aufgerufen, und das Brain füllt sich mit Rauschen.
• Benennen Sie die Form einer guten Eingabe. „Eine Frage in natürlicher Sprache, keine Stichwörter“ ändert, was das Modell sendet.
• Geben Sie Fehler unverändert zurück. Die Fehler von Hive sind so formuliert, dass man darauf reagieren kann – ein abgelehntes Duplikat liefert das vorhandene Neuron zurück, damit das Modell stattdessen aktualisieren oder verknüpfen kann. Unterdrücken Sie das, geht diese Korrekturmöglichkeit verloren.

Schutzmaßnahmen, die Sie in Ihrem Code behalten sollten

Dem Modell die Entscheidung zu überlassen, wann es aufruft, bedeutet nicht, ihm uneingeschränkte Befugnis zu geben. Behalten Sie diese auf Ihrer Seite:

• Minimale Rechte. Erteilen Sie dem Dienstkonto nur Lesezugriff, es sei denn, der Agent muss wirklich schreiben. Der Zugriff gilt pro Brain.
• Getrennte Identitäten pro Integration. Ein Dienstkonto pro Agent, damit Prüfverlauf und Widerruf aussagekräftig sind.
• Destruktive Aufrufe bestätigen lassen. Löschen-Tools lässt man am besten ganz aus dem Toolset heraus oder schützt sie durch eine menschliche Freigabe.
• Aktivieren Sie die Prüfung für alles Regulierte – jeder Schreibvorgang ist dann dem aufrufenden Dienstkonto zuordenbar. Kostenpflichtige Funktion; siehe Lizenzierung & Tarife.

Wann imperative Aufrufe richtig sind

Es gibt einen berechtigten Fall für direkte Aufrufe: deterministische, nicht konversationelle Arbeit. Massenimport von Dokumenten, ein nächtlicher Abgleich, ein Provisionierungsskript, eine Migration. Es ist keine Beurteilung nötig, also gibt es nichts zu delegieren – verwenden Sie die REST-API oder rufen Sie die MCP-Tools direkt auf und halten Sie es einfach.