agentHints: CLIs für die Kommunikation mit Agenten schulen

Dies ist eine 10-teilige Serie, die zeigt, wie Apidog das Apidog CLI entwickelt hat, ein Befehlszeilentool für API-Tests und das API-Lebenszyklusmanagement. Lesen Sie sie der Reihe nach oder springen Sie zu einem Beitrag, der Sie interessiert:

Traditionelle CLI-Ausgabe ist für Menschen. Agenten benötigen strukturierte Ergebnisse, Fehlerursachen und Vorschläge für nächste Schritte. agentHints wandelt Produktexpertise in maschinenlesbare Anleitungen um.

Die Lücke in der CLI-Ausgabe

Traditionelle CLI-Ausgabe ist für **Menschen** konzipiert.

Das funktioniert für Menschen. Menschen können:

• Vage Nachrichten interpretieren
• Entscheiden, was als Nächstes zu tun ist
• Kontext aus früheren Befehlen erinnern
• Domänenwissen anwenden, um fortzufahren

**Aber Agenten arbeiten anders.**

Was Agenten wirklich brauchen

Agenten lesen nicht nur Ergebnisse. Sie müssen **Ergebnisse mit der nächsten Aufgabenkette verbinden.**

Ein Mensch sieht "Ressource erfolgreich erstellt" und weiß: "Ich sollte wahrscheinlich überprüfen, was erstellt wurde, und dann vielleicht einige Tests durchführen."

Ein Agent sieht "Ressource erfolgreich erstellt" und... hat keine Ahnung, was als Nächstes zu tun ist.

agentHints: Die Lösung

Apidog CLI fügt `agentHints` zu seiner Ausgabe hinzu.

So sieht eine typische Antwort aus:

{
  "success": true,
  "data": {
    "id": "12345",
    "name": "Health Check Test Case"
  },
  "agentHints": {
    "summary": "Test case created successfully.",
    "nextSteps": [
      "Read the created test case back to confirm structure.",
      "Add assertions if the test case needs response validation.",
      "Add the test case to a test scenario for integration testing.",
      "Run related tests after adding to scenario."
    ]
  }
}

**Drei Komponenten:**

Das Problem der Ausführungsträgheit

Hier ist ein reales Problem, das wir beobachtet haben:

**Nach dem erfolgreichen Erstellen einer Ressource fährt das Modell oft direkt damit fort, den nächsten Schreibvorgang zu generieren.**

Beispiel:

Agent: Erstellt Testfall
CLI: Meldet Erfolg
Agent: Erstellt sofort Testszenario (ohne Rücklesen)
Agent: Führt sofort Tests aus
Ergebnis: Szenario hat falsche Struktur, Tests schlagen fehl

In komplexen Geschäftsprozessen ist eine **mechanische kontinuierliche Ausführung nicht angemessen.**

Der korrekteste Ansatz ist oft:

1. Ressource erstellen
2. **Zuerst zurücklesen**
3. Struktur bestätigen
4. Dann fortfahren

Warum das Rücklesen wichtig ist

Das Überspringen des Rücklesens verursacht reale Probleme:

Wenn die tatsächliche Struktur nicht zurückgelesen wird, fährt der Agent leicht damit fort, basierend auf seiner eigenen Vermutung zu schreiben – nicht auf tatsächlichen Daten.

agentHints als Navigator

agentHints wandelt Produktexpertise in maschinenlesbare Vorschläge für nächste Schritte um.

Es erscheint **genau dort, wo der Agent Entscheidungen treffen muss.**

Beispiel nach dem Erstellen eines Testfalls:

{
  "agentHints": {
    "nextSteps": [
      "Read back the created test case with --with-case-detail flag.",
      "Validate any updates with cli-schema before writing.",
      "Run tests after completing test scenario."
    ]
  }
}

Der Agent:

1. Liest die Ausgabe
2. Parst `agentHints`
3. Folgt `nextSteps[0]`: liest den Testfall zurück
4. Bestätigt die tatsächliche Struktur
5. Fährt dann mit genauen Informationen fort

CLI Rollentransformation

Dies verändert, was CLI im Agenten-Workflow bedeutet.

**CLI wird zu einem leichtgewichtigen Zustandsnavigator.**

Integrierte Workflow-Bäume

Apidog CLI verfügt über **Tausende von baumstrukturierten Workflows.**

Das sind nicht nur fest kodierte Vorschläge. Sie sind:

Beispiel nach erfolgreicher Aktualisierung des Testszenarios:

{
  "agentHints": {
    "summary": "Test scenario updated successfully.",
    "nextSteps": [
      "Run the test scenario to verify changes.",
      "Check the test report for any failures.",
      "If failures occur, read back scenario steps for debugging."
    ]
  }
}

Beispiel nach Validierungsfehler:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'comparator' has invalid value",
    "details": [...]
  },
  "agentHints": {
    "summary": "Validation failed. Fix the errors and re-validate.",
    "nextSteps": [
      "Review the error details in the output.",
      "Adjust the JSON file based on error suggestions.",
      "Re-run cli-schema validate before writing."
    ]
  }
}

**Selbst Fehler werden navigierbar.**

Der sicherere Loop mit agentHints

Verfolgen wir einen vollständigen Workflow mit agentHints:

Schritt 1: Agent erstellt Testfall
        ↓
CLI-Ausgabe: success + agentHints
        ↓
agentHints.nextSteps[0]: "Lesen Sie den erstellten Testfall zurück"
        ↓
Schritt 2: Agent liest zurück (mit tatsächlicher Struktur)
        ↓
CLI-Ausgabe: Testfallstruktur + agentHints
        ↓
agentHints.nextSteps[0]: "Assertions hinzufügen, falls benötigt"
        ↓
Schritt 3: Agent fügt Assertions hinzu (basierend auf tatsächlicher Struktur)
        ↓
CLI-Ausgabe: success + agentHints
        ↓
agentHints.nextSteps[0]: "Tests ausführen"
        ↓
Schritt 4: Agent führt Tests aus
        ↓
CLI-Ausgabe: Testbericht

**Jeder Schritt wird geführt. Keine blinden Sprünge. Keine Annahmen.**

Vergleich: Mit und ohne agentHints

Was kommt als Nächstes

Nachdem CLI Agenten durch nächste Schritte führen kann, bleibt die Frage:

**Woher wissen Agenten überhaupt, welchem Workflow sie folgen sollen?**

In Teil 5, SKILL: Operative Erfahrung als Code bereitstellen, werden wir untersuchen, wie SKILL Workflow-Wissen verpackt – wann Befehle zu verwenden sind, welche Reihenfolge einzuhalten ist und welche Felder nicht geraten werden sollten.

Wichtige Erkenntnisse

• Traditionelle CLI-Ausgabe ist menschenzentriert; Agenten benötigen strukturierte Anleitung
• agentHints liefert eine Zusammenfassung + Vorschläge für nächste Schritte in der JSON-Ausgabe
• Ausführungsträgheit führt dazu, dass Agenten das Rücklesen überspringen; agentHints verhindert dies
• CLI wandelt sich vom Ausführenden zum Navigator
• Integrierte Workflow-Bäume machen jeden Schritt navigierbar
• Selbst Fehler werden mit agentHints handhabbar

Laden Sie Apidog herunter, um APIs in einem einzigen Arbeitsbereich zu entwerfen, zu simulieren, zu testen und zu dokumentieren. Erfahren Sie mehr über das Apidog CLI für Befehlszeilen-API-Tests, CI-Automatisierung und KI-Agenten-Workflows.