iterative-retrieval

Iteratives Retrieval-Muster

Löst das „Kontextproblem“ in Multi-Agenten-Workflows, bei denen Subagenten nicht wissen, welchen Kontext sie benötigen, bis sie mit der Arbeit beginnen.

Wann aktivieren

• Wenn Subagenten erzeugt werden, die Code-Repository-Kontext benötigen, den sie nicht vorhersagen können
• Beim Aufbau von Multi-Agenten-Workflows, bei denen Kontext schrittweise verfeinert wird
• Bei Fehlern wie „Kontext zu groß“ oder „fehlender Kontext“ in Agentenaufgaben
• Beim Entwurf von RAG-ähnlichen Abrufpipelines zur Code-Erkundung
• Bei Optimierung des Tokenverbrauchs in der Agentenorchestrierung

Das Problem

Subagenten werden mit begrenztem Kontext erzeugt. Sie wissen nicht:

• Welche Dateien relevanten Code enthalten
• Welche Muster im Code-Repository existieren
• Welche Terminologie das Projekt verwendet

Standardansätze scheitern:

• Alles senden: Überschreitet Kontextgrenzen
• Nichts senden: Dem Agenten fehlen kritische Informationen
• Raten, was benötigt wird: Oft falsch

Die Lösung: Iteratives Retrieval

Ein 4-Phasen-Zyklus, der den Kontext schrittweise verfeinert:

┌─────────────────────────────────────────────┐
│                                             │
│   ┌──────────┐      ┌──────────┐            │
│   │ DISPATCH │─────│ EVALUATE │            │
│   └──────────┘      └──────────┘            │
│        ▲                  │                 │
│        │                  ▼                 │
│   ┌──────────┐      ┌──────────┐            │
│   │   LOOP   │─────│  REFINE  │            │
│   └──────────┘      └──────────┘            │
│                                             │
│        Maximal 3 Zyklen, dann fortfahren    │
└─────────────────────────────────────────────┘

Phase 1: DISPATCH

Erste breite Abfrage, um Kandidatendateien zu sammeln:

// Starten Sie mit der übergeordneten Absicht
const initialQuery = {
  patterns: ['src/**/*.ts', 'lib/**/*.ts'],
  keywords: ['authentifizierung', 'benutzer', 'sitzung'],
  excludes: ['*.test.ts', '*.spec.ts']
};

// An Retrieval-Agenten senden
const candidates = await retrieveFiles(initialQuery);

Phase 2: EVALUATE

Bewertung der abgerufenen Inhalte auf Relevanz:

function evaluateRelevance(files, task) {
  return files.map(file => ({
    path: file.path,
    relevance: scoreRelevance(file.content, task),
    reason: explainRelevance(file.content, task),
    missingContext: identifyGaps(file.content, task)
  }));
}

Bewertungskriterien:

• Hoch (0.8-1.0): Implementiert die Zielfunktionalität direkt
• Mittel (0.5-0.7): Enthält verwandte Muster oder Typen
• Gering (0.2-0.4): Entfernt verwandt
• Keine (0-0.2): Nicht relevant, ausschließen

Phase 3: REFINE

Suchkriterien basierend auf der Bewertung aktualisieren:

function refineQuery(evaluation, previousQuery) {
  return {
    // Neue Muster hinzufügen, die in Dateien mit hoher Relevanz gefunden wurden
    patterns: [...previousQuery.patterns, ...extractPatterns(evaluation)],

    // Im Code-Repository gefundene Terminologie hinzufügen
    keywords: [...previousQuery.keywords, ...extractKeywords(evaluation)],

    // Bestätigte irrelevante Pfade ausschließen
    excludes: [...previousQuery.excludes, ...evaluation
      .filter(e => e.relevance < 0.2)
      .map(e => e.path)
    ],

    // Auf spezifische Lücken abzielen
    focusAreas: evaluation
      .flatMap(e => e.missingContext)
      .filter(unique)
  };
}

Phase 4: LOOP

Wiederholung mit verfeinerten Kriterien (maximal 3 Zyklen):

async function iterativeRetrieve(task, maxCycles = 3) {
  let query = createInitialQuery(task);
  let bestContext = [];

  for (let cycle = 0; cycle < maxCycles; cycle++) {
    const candidates = await retrieveFiles(query);
    const evaluation = evaluateRelevance(candidates, task);

    // Prüfen, ob ausreichend Kontext vorhanden ist
    const highRelevance = evaluation.filter(e => e.relevance >= 0.7);
    if (highRelevance.length >= 3 && !hasCriticalGaps(evaluation)) {
      return highRelevance;
    }

    // Verfeinern und fortfahren
    query = refineQuery(evaluation, query);
    bestContext = mergeContext(bestContext, highRelevance);
  }

  return bestContext;
}

Praktische Beispiele

Beispiel 1: Fehlerbehebungskontext

Aufgabe: „Fehler beim Ablauf des Authentifizierungstokens beheben“

Zyklus 1:
  DISPATCH: Suche nach „token“, „auth“, „ablauf“ in src/**
  EVALUATE: Gefunden auth.ts (0.9), tokens.ts (0.8), user.ts (0.3)
  REFINE: Schlüsselwörter „aktualisieren“, „jwt“ hinzufügen; user.ts ausschließen

Zyklus 2:
  DISPATCH: Suche mit verfeinerten Begriffen
  EVALUATE: Gefunden session-manager.ts (0.95), jwt-utils.ts (0.85)
  REFINE: Ausreichender Kontext (2 Dateien mit hoher Relevanz)

Ergebnis: auth.ts, tokens.ts, session-manager.ts, jwt-utils.ts

Beispiel 2: Funktionsimplementierung

Aufgabe: „Ratenbegrenzung zu API-Endpunkten hinzufügen“

Zyklus 1:
  DISPATCH: Suche „rate“, „limit“, „api“ in routes/**
  EVALUATE: Keine Treffer – Code-Repository verwendet „drossel“-Terminologie
  REFINE: Schlüsselwörter „drossel“, „middleware“ hinzufügen

Zyklus 2:
  DISPATCH: Suche mit verfeinerten Begriffen
  EVALUATE: Gefunden throttle.ts (0.9), middleware/index.ts (0.7)
  REFINE: Router-Muster benötigt

Zyklus 3:
  DISPATCH: Suche „router“, „express“ Muster
  EVALUATE: Gefunden router-setup.ts (0.8)
  REFINE: Ausreichender Kontext

Ergebnis: throttle.ts, middleware/index.ts, router-setup.ts

Integration mit Agenten

Verwendung in Agenten-Prompts:

Beim Abrufen von Kontext für diese Aufgabe:
1. Beginnen Sie mit einer breiten Schlüsselwortsuche
2. Bewerten Sie die Relevanz jeder Datei (Skala 0–1)
3. Identifizieren Sie, welcher Kontext noch fehlt
4. Verfeinern Sie die Suchkriterien und wiederholen Sie (maximal 3 Zyklen)
5. Geben Sie Dateien mit Relevanz >= 0.7 zurück

Best Practices

1. Breit beginnen, schrittweise eingrenzen – Erste Abfragen nicht übermäßig spezifizieren
2. Code-Repository-Terminologie lernen – Erster Zyklus zeigt oft Namenskonventionen
3. Nachverfolgen, was fehlt – Explizite Lückenidentifikation treibt Verfeinerung voran
4. Bei „gut genug“ anhalten – 3 Dateien mit hoher Relevanz sind besser als 10 mittelmäßige
5. Sicher ausschließen – Dateien mit geringer Relevanz werden nicht relevant

Verwandtes

• Der Langform-Leitfaden – Abschnitt zur Subagenten-Orchestrierung
• continuous-learning-Fähigkeit – Für Muster, die sich im Laufe der Zeit verbessern
• Agentendefinitionen, die mit ECC gebündelt sind (manueller Installationspfad: agents/)