RAG-Tutorial für KI-Agenten: Retrieval mit Quellenangaben

RAG im Produktivbetrieb gibt einem KI-Agenten eine eng begrenzte Suchfunktion. Bei Connic liegen vertrauenswürdige Inhalte in einem benannten Namespace; ein zweckgebundenes Python-Tool kapselt die semantische Suche. Die Agentenkonfiguration in YAML erzwingt Lesezugriff und Tests prüfen Tool-Auswahl sowie Quellenangaben vor dem Deployment.

Früher Knowledge Base

Welche Regeln für Retrieval im Produktivbetrieb gelten

Retrieval-augmented Generation ergänzt einen Agenten-Run um relevante Passagen, bevor das KI-Modell antwortet. Die semantische Suche findet Passagen nach ihrer Bedeutung. Sie entscheidet jedoch nicht, welche Inhalte freigegeben sind, ob der Agent hineinschreiben darf oder wie die Antwort ihre Belege zitiert. Diese Entscheidungen gehören in die Konfiguration von Tool und Agenten.

Schritt 1: Freigegebene Inhalte in einem Namespace indexieren

Auf der Seite Retrieval lassen sich die Dokumente hochladen, die der Agent verwenden darf. Sie erhalten einen Namespace wie support.approved und eine aussagekräftige Eintrags-ID wie refund-policy-2026. Eine Abfrage gegen einen übergeordneten Namespace durchsucht auch dessen untergeordnete Namespaces. Eine stabile Hierarchie lässt daher Raum, Richtlinien, Produktdokumentation und Runbooks später zu trennen.

Uploads werden asynchron indexiert. Nach Abschluss des Indexierungsauftrags sollten repräsentative Fragen über die Abfrage im Dashboard geprüft werden, bevor der Index mit einem Agenten verbunden wird. Upload und Prüfung von Retrieval-Inhalten.

Schritt 2: Ein zweckgebundenes Such-Tool bereitstellen

Eigene Tools sind normale typisierte Python-Funktionen unter tools/. Ein Decorator ist nicht erforderlich. Connic erstellt aus Funktionssignatur und Docstring das Schema, das das KI-Modell sieht. Dieser Wrapper fixiert den Namespace und gibt nur die Passage und Quellenfelder zurück, die der Support-Agent benötigt:

from connic.tools import retrieval_query

async def search_support_docs(question: str) -> list[dict]:
    """Find approved support passages for a customer question.

    Args:
        question: The customer's policy or product question.
    """
    result = await retrieval_query(
        query=question,
        namespace="support.approved",
        min_score=0.35,
        max_results=5,
    )

    matches = []
    for item in result.get("results", []):
        source = item["entry_id"]
        page = item.get("page_number")
        citation = f"{source}, p. {page}" if page else source
        matches.append({
            "passage": item["content"],
            "citation": citation,
        })
    return matches

Die vordefinierte Funktion retrieval_query liefert nach Relevanz sortierte Chunks mit Quellenfeldern wie entry_id, namespace und, bei Quellen mit Seiten, page_number. Der Wrapper wandelt diese Felder in das Format für Quellenangaben um, das das Produkt darstellt. Unsere Plattform liefert die Belege; Tool und Prompt bestimmen, wie die Antwort sie zitiert.

retrieval_query direkt anzuhängen, eignet sich für einen Prototyp oder einen vielseitig einsetzbaren internen Agenten. Ein produktiver Support-Agent sollte weder beliebige Namespaces wählen noch Suchparameter zur Laufzeit einstellen. Er sollte auch nicht retrieval_store erhalten, sofern das Schreiben indexierter Inhalte nicht zu seinen Aufgaben gehört. Für lesende Agenten bleibt die Indexierung im Dashboard, in einer Retrieval-Quelle oder in einer kontrollierten API-Pipeline. Referenz für Custom Retrieval Wrapper.

Schritt 3: Dieselbe Begrenzung im Agenten-YAML erzwingen

Der Wrapper wird über Modul- und Funktionsnamen eingebunden. Der Retrieval-Block bildet eine zweite, durch die Runtime erzwungene Begrenzung: Dieser Agent erreicht nur support.approved und dessen untergeordnete Namespaces und kann dort keine Inhalte speichern oder löschen.

version: "1.0"

name: support-agent
type: llm
model: connic/gpt-5.6-terra
description: "Answers support questions from approved documentation"
system_prompt: |
  Answer policy and product questions only from passages returned by
  search_support_docs. Cite every supported claim in square brackets
  using the citation value from the tool result.

  If the search returns no relevant passage, say that the approved
  documentation does not answer the question. Do not guess.

tools:
  - support_knowledge.search_support_docs

retrieval:
  namespaces:
    support.approved:
      prevent_write: true
      prevent_delete: true

Der Wrapper verbessert die Tool-Schnittstelle; der Access-Block in YAML begrenzt die Möglichkeiten des zugrunde liegenden Retrieval-Aufrufs. Beides sollte erhalten bleiben. Ändert ein späteres Refactoring den Namespace im Wrapper, greift weiterhin die Allowlist auf Agent-Ebene, statt den Zugriff unbemerkt auszuweiten.

Schritt 4: Retrieval-Nutzung und Quellenangaben testen

Für deterministische Agententests wird der eigene Wrapper gemockt. Der folgende Mock gibt eine bekannte Passage und Quellenangabe zurück, ohne vom aktuellen Inhalt des Index abhängig zu sein. Gemockte eigene Tool-Aufrufe erscheinen weiterhin im Trace und zählen für Tool-Call-Assertions.

def mock_support_knowledge_search_support_docs(tool_name, params, context):
    return [{
        "passage": "Enterprise refunds are available within 60 days.",
        "citation": "refund-policy-2026, p. 12",
    }]

version: "1.0"

tests:
  - name: cites_the_refund_policy
    payload: "What is the enterprise refund window?"
    mocks: support_knowledge
    strict_mocks: true
    expected_tool_calls:
      - support_knowledge.search_support_docs: invocations == 1
    expected_result: '"[refund-policy-2026, p. 12]" in output'

  - name: skips_retrieval_for_a_greeting
    payload: "Say hello."
    mocks: support_knowledge
    strict_mocks: true
    expected_no_tool_calls:
      - support_knowledge.search_support_docs

Der erste Fall erkennt Änderungen an KI-Modell oder Prompt, durch die keine Suche mehr stattfindet oder die Quellenreferenz entfällt. Der zweite erkennt unnötiges Retrieval bei einem Prompt, den das KI-Modell ohne Unternehmenswissen beantworten kann. Die Suite wird mit connic test ausgeführt; dieselben Tests laufen als Deployment-Prüfung. Ein zusätzlicher nicht gemockter Fall in einem Test-Environment erkennt auch Änderungen an Indexierung oder Relevanz. Referenz für Tool-Call-Assertions.

Prüfungen vor dem Produktivstart

Weitere Details enthalten die Referenz zu Retrieval-Abfragen und Speicherung und das Quickstart-Beispiel.