Geben Sie einem KI-Agenten Schreibzugriff auf Ihr API-Projekt, kann er echten Schaden anrichten – nicht böswillig, sondern weil er genau das tut, was Ihr Prompt impliziert. „Benutzerendpunkte aufräumen“ kann zum Löschen einer noch genutzten Route führen. „Schema aktualisieren“ kann ein Datenmodell überschreiben, auf das andere Endpunkte verweisen. Der Agent weiß nicht, was produktiv genutzt wird; er sieht nur Ressourcen, auf die er zugreifen darf.
Apidog noch heute ausprobieren
Das ist ein neues Risikomuster: Ein menschlicher Entwickler würde vor dem Löschen eines Endpunkts vermutlich innehalten. Ein Agent in einer Terminal-Schleife nicht. Er führt den Befehl aus, erhält eine Erfolgsmeldung und macht weiter. Wenn der Befehl gegen Ihren Main-Branch lief, ist die Änderung bereits in Ihrer API-Designquelle.
Die Lösung ist nicht, Agenten auszuschließen. Geben Sie ihnen stattdessen eine Sandbox, aus der sie nicht herauskommen. Apidogs KI-Branch isoliert jede Agentenänderung in einem eigenen Branch. Der Quell-Branch bleibt unverändert, und nichts erreicht main, bevor ein Mensch den Diff geprüft und die Änderung gemergt hat.
Dieser Beitrag zeigt den CLI-Workflow Schritt für Schritt. Für die Design-Grundlagen lesen Sie außerdem die ausführlichere Erklärung zu KI-Branch und sichereren agentengesteuerten Änderungen.
Warum Schreibzugriff für Agenten standardmäßig gefährlich ist
Viele Tools kennen nur eine Berechtigungsstufe: Zugriff auf das gesamte Projekt. Kann ein Agent einen Endpunkt erstellen, kann er ihn häufig auch löschen. Kann er ein Schema ändern, kann er es auch durch eine inkompatible Variante ersetzen.
Zwischen diesen beiden Zuständen fehlt dann eine wichtige Kontrollschicht:
- Der Agent schlägt eine Änderung vor.
- Die Änderung landet unmittelbar in der Quelle der Wahrheit.
Typische Fehler sehen so aus:
- Überschreiben: Der Agent generiert ein Schema auf Basis eines unvollständigen API-Verständnisses neu und entfernt Felder, die andere Endpunkte benötigen.
- Löschen: Der Agent „konsolidiert“ Endpunkte und entfernt Routen, die aktive Clients weiterhin aufrufen.
- Stilles Abdriften: Der Agent führt viele kleine Änderungen in einer Sitzung aus. Jede einzelne wirkt plausibel, aber zusammen weicht die API von dem ab, was Sie ausliefern wollten.
Das Ziel ist daher nicht, Agenten weniger leistungsfähig zu machen. Das Ziel ist, den produktiven Branch für direkte Agentenänderungen unerreichbar zu machen.
Die Kernlösung: ein isolierter KI-Branch
Ein KI-Branch ist ein spezieller Sprint-Branch für externe KI- und CLI-Operationen. Der Agent bearbeitet Ressourcen ausschließlich in diesem Branch. Ihr Quell-Branch und main bleiben unverändert, bis Sie bewusst mergen.
1. Apidog CLI installieren und anmelden
Installieren Sie zuerst die Apidog CLI und authentifizieren Sie sich mit einem Zugriffstoken:
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Verwenden Sie dafür kein persönliches Owner-Token, wenn ein eingeschränktes Automatisierungstoken ausreicht.
2. KI-Branch von main erstellen
Erstellen Sie für jede abgegrenzte Agentenaufgabe einen eigenen KI-Branch:
apidog branch create --type ai \
--name "ai/20260708-from-main-user-register" \
--from main \
--project <PROJECT_ID>
Die Benennung enthält hier:
-
ai: Kennzeichnung für Agentenarbeit -
20260708: Erstellungsdatum -
from-main: Quell-Branch -
user-register: Zweck der Änderung
Wichtig: Der Branch wird von main erstellt, verändert main aber nicht.
Ein KI-Branch startet außerdem leer. Er kopiert nicht automatisch das gesamte Projekt. Stattdessen importieren Sie nur die Ressourcen, die der Agent wirklich bearbeiten soll. Das begrenzt den möglichen Schaden auf einen explizit definierten Bereich.
Alle Optionen eines Befehls sehen Sie über -h:
apidog branch create -h
Quellressourcen vor der Bearbeitung importieren
Da der KI-Branch leer beginnt, importieren Sie zuerst die konkreten Endpunkte, Schemata oder Dokumente, die der Agent benötigt.
Beispiel: Importieren Sie die Endpunkte 1 und 2 sowie das Datenschema 3 aus main:
apidog branch pick-to \
--type ai \
--from main \
--to "ai/20260708-from-main-user-register" \
--endpoint-ids 1,2 \
--data-schema-ids 3 \
--project <PROJECT_ID>
Danach enthält der KI-Branch ausschließlich Kopien dieser Ressourcen:
- Endpunkt
1 - Endpunkt
2 - Datenschema
3
Der Agent arbeitet nur mit diesen Kopien. Löscht er einen Endpunkt, löscht er nicht die produktive Route auf main, sondern nur die Branch-Kopie.
Das ist der entscheidende Unterschied zwischen:
Der Agent hat unsere API zerstört.
und:
Der Agent hat eine isolierte Kopie verändert, die wir verwerfen können.
Wenn Sie die CLI aus einem Code-Agenten heraus verwenden, kann der Agent die Befehlsausgabe direkt verarbeiten. Die Apidog CLI gibt strukturiertes JSON zurück, einschließlich agentHints.nextSteps. Damit kann der Agent das Ergebnis eines Schritts auswerten und den nächsten Schritt ableiten. Ein konkretes Editor-Beispiel finden Sie im Leitfaden zu apidog-cli in Cursor.
Agenten bearbeiten lassen, dann den Diff prüfen
Nach dem Import kann der Agent im KI-Branch arbeiten. Er kann dort beispielsweise:
- Endpunkte erstellen oder aktualisieren
- Schemata ändern
- Dokumentation anpassen
- Testszenarien erstellen oder bearbeiten
- Ressourcen im Branch löschen
Alle diese Schreiboperationen bleiben im KI-Branch isoliert.
Der nächste Schritt ist nicht optional: Prüfen Sie den Diff, bevor Sie etwas mergen.
Kontrollieren Sie die Änderungen über die CLI oder im Apidog-Client und vergleichen Sie sie mit der ursprünglichen Aufgabe. Achten Sie insbesondere auf:
- versehentlich entfernte Felder
- geänderte Request- oder Response-Formate
- gelöschte Endpunkte
- unerwartete Änderungen an abhängigen Schemata
- zusätzliche Ressourcen, die nicht Teil der Aufgabe waren
Wenn der Agent die Aufgabe falsch interpretiert hat, verwerfen Sie den Branch. Sie müssen keine Produktionsänderung zurückrollen.
Änderungen über einen Merge-Request übernehmen
Wie Sie Änderungen übernehmen, hängt vom Ziel-Branch ab. Für main sollte Branch-Schutz aktiviert sein.
Direkter Merge in einen ungeschützten Branch
Ist der Ziel-Branch nicht geschützt, können Sie konkrete Ressourcen direkt mergen:
apidog branch merge \
--type ai \
--from "ai/20260708-from-main-user-register" \
--to main \
--endpoint-ids 1,2 \
--data-schema-ids 3 \
--project <PROJECT_ID>
Auch hier bestimmen die Ressourcen-IDs exakt, was übertragen wird.
Merge-Request für einen geschützten Main-Branch
Bei einem geschützten main wird ein direkter Merge blockiert. Erstellen Sie stattdessen einen Merge-Request:
apidog merge-request create \
--from "ai/20260708-from-main-user-register" \
--to main \
--endpoint-ids 1,2 \
--data-schema-ids 3 \
--reviewer-ids <REVIEWER_USER_IDS> \
--description "AI branch: user register changes" \
--project <PROJECT_ID>
Der Merge-Request ist der bevorzugte Weg für Agentenänderungen:
- Der Agent erzeugt die Änderung im isolierten Branch.
- Ein Mensch prüft den Diff.
- Ein Reviewer genehmigt den Merge-Request.
- Erst danach landet die Änderung in
main.
Der Agent schreibt damit nie direkt in den Main-Branch. Er kann nur vorschlagen, dass ein Mensch seine Änderung übernimmt.
Außerdem werden nur die aufgelisteten Ressourcen-IDs gemergt. Hat der Agent etwas verändert, das nicht ausgeliefert werden soll, lassen Sie diese ID beim Merge weg.
Dieses Vorgehen entspricht einem Git-nativen API-Kollaborationsworkflow: Branch erstellen, Änderung vorschlagen, prüfen, mergen. Ein KI-Branch wendet dieselbe Disziplin auf nicht-menschliche Mitwirkende an.
Gemergte und verworfene Branches bereinigen
Archivieren Sie KI-Branches, sobald sie gemergt oder verworfen wurden. Das hält die Branch-Liste übersichtlich und reduziert Verwechslungen.
apidog branch archive "ai/20260708-from-main-user-register" \
--type ai \
--project <PROJECT_ID>
Eine sinnvolle Regel lautet:
Ein KI-Branch pro Aufgabe.
Ein Branch sollte genau eine Arbeitseinheit enthalten:
- Aufgabe definieren
- Ressourcen importieren
- Agent bearbeiten lassen
- Diff prüfen
- Mergen oder verwerfen
- Branch archivieren
Vermeiden Sie Branches, in denen sich mehrere unabhängige Agentensitzungen ansammeln. Solche Diffs werden schwer prüfbar.
Sichere Agenten-Hygiene rund um den Branch
Der KI-Branch liefert Isolation. Für einen robusten Workflow brauchen Sie zusätzlich klare Sicherheitsregeln.
Zugriffstoken mit geringsten Berechtigungen verwenden
Das Token aus folgendem Befehl bestimmt, was der Agent tun kann:
apidog login --with-token <YOUR_ACCESS_TOKEN>
Geben Sie einem Automatisierungstoken nur Zugriff auf die benötigten Projekte und Ressourcen. Verwenden Sie nicht Ihr persönliches Owner-Token, nur weil es bequem ist.
Falls ein Token offengelegt wird oder sich ein Agent fehlerhaft verhält, begrenzt sein Scope den möglichen Schaden.
Main-Branch schützen
Ein geschützter main macht die Code-Review-Regel technisch durchsetzbar:
- Direkte Merges werden blockiert.
- Änderungen müssen über
merge-request createlaufen. - Ein menschlicher Reviewer muss zustimmen.
Damit wird „vor dem Mergen prüfen“ von einer Empfehlung zu einer festen Workflow-Regel.
Jeden Diff prüfen
Isolation hilft nur, wenn jemand den Diff tatsächlich liest. Machen Sie die Prüfung zu einem verpflichtenden Schritt.
Auch ein Agent, der mehrere Tage zuverlässig gearbeitet hat, kann einen Prompt später falsch interpretieren. Prüfen Sie daher bei jeder Änderung:
- Was wurde hinzugefügt?
- Was wurde geändert?
- Was wurde gelöscht?
- Welche Abhängigkeiten könnten betroffen sein?
Delegieren, dann verifizieren
Das zentrale Muster lautet:
- Delegieren Sie eine klar abgegrenzte Aufgabe.
- Lassen Sie den Agenten im isolierten Branch arbeiten.
- Prüfen Sie das Ergebnis.
- Übernehmen Sie nur die gewünschten Änderungen.
Der Agent erledigt die Arbeit. Sie verantworten die Abnahme.
Dasselbe Prinzip gilt für Tests: Der Agent kann eine Testsuite ausführen, aber Sie prüfen die Ergebnisse des Test-Harness und den Exit-Code, bevor Sie den Resultaten vertrauen.
Wenn Sie Ihre API-Spezifikation zusätzlich in Git versionieren, erhalten Sie mit einem OpenAPI-Versionskontrollworkflow eine zweite Historie für zusätzliche Diff- und Audit-Prüfungen.
Der End-to-End-Workflow
Verwenden Sie diese Reihenfolge für jede Agentenaufgabe:
- Erstellen Sie einen KI-Branch von
main:
apidog branch create --type ai
- Importieren Sie nur die benötigten Endpunkte und Schemata:
apidog branch pick-to
Lassen Sie den Agenten ausschließlich im KI-Branch arbeiten.
Prüfen Sie den Diff über CLI oder Apidog-Client.
Erstellen Sie für einen geschützten
maineinen Merge-Request:
apidog merge-request create
- Archivieren Sie den Branch nach Merge oder Verwerfung:
apidog branch archive
Zu keinem Zeitpunkt sollte der Agent einen aktiven Endpunkt auf main direkt überschreiben oder löschen können. Der schlimmste Fall ist dann eine fehlerhafte Änderung in einer isolierten Scratch-Kopie, die Sie nicht mergen.
Agenten arbeiten lassen, ohne ihnen die Schlüssel zu geben
Agenten sind nützlich, weil sie selbstständig handeln. Genau deshalb ist uneingeschränkter Schreibzugriff riskant.
Mit einem isolierten KI-Branch, einem geschützten Main-Branch, Tokens mit geringsten Berechtigungen und einer verpflichtenden Prüfung wird aus „Der Agent hat unsere API zerstört“ ein Diff, den Sie prüfen und bei Bedarf ablehnen.
Apidog integriert diesen Workflow, sodass Sie die Sicherheitsmechanismen nicht aus mehreren Tools zusammensetzen müssen. Installieren Sie die Apidog CLI, erstellen Sie einen KI-Branch und lassen Sie Agenten gegen eine Kopie statt gegen das Original arbeiten. Laden Sie Apidog herunter, um den KI-Branch-Workflow auszuprobieren, und lesen Sie vor dem Einsatz in Produktionsworkflows die vollständige KI-Branch-Dokumentation.
Top comments (0)