Steuern und Betreiben von Agenten – Beobachtbarkeit, Tools, MCP, Geheimdaten, Hooks und Zuverlässigkeit

  • 5 Minuten

In dieser Lektion lernen Sie:

  • Ermitteln der Nachweise und Artefakte, die für die Agentenarbeit erforderlich sind

  • So steuern Sie Tools, MCP-Integrationen und geheime Schlüssel sicher

  • So erzwingen Hooks Leitplanken und Audit-Protokollierung

  • Wie Sie Zuverlässigkeit durch den Einsatz von Wiederholungsversuchen, Eskalationen und minimalen Berechtigungen gestalten

Erforderliche Nachweise und Artefakte für Agents

Ein Agentsystem muss sichtbare Artefakte für jede sinnvolle Aktion erzeugen. Ohne Artefakte können Sie das Verhalten nicht zuverlässig überprüfen, Fehler nicht debuggen oder eine Post-hoc-Analyse durchführen.

In GitHub wird Observierbarkeit erreicht durch Artefakte wie:

  • Pull-Requests und Zeitpläne für PRs,

  • Commits und Verzweigungsverlauf

  • Workflowausführungen und Jobprotokolle,

  • erforderliche Überprüfungen und Scan-Ergebnisse und

  • hochgeladene Workflowartefakte (z. B. Testberichte).

Minimaler Feststellbarkeitssatz

Eine gut gestaltete Agentaufgabe sollte sichtbare, beprüfbare Nachweise mithilfe von GitHub nativen Artefakten erzeugen:

  • ein strukturierter Plan, der in der Regel in der Beschreibung eines Pull-Requests oder in einer Diskussion enthalten ist

  • einen eingeschränkter Pull-Request- und Commit-Verlauf

  • Links zu Workflow-Ausführungen für erforderliche Prüfungen

  • hochgeladene Artefakte (z. B. Protokolle oder Berichte)

  • Ergebnisse überprüfen (Genehmigungen oder angeforderte Änderungen)

Hochladen von Workflowartefakten zum Überprüfen und Debuggen

Das Hochladen von Artefakten macht Nachweise dauerhaft und bearbeitbar, auch wenn Protokolle nach unten scrollen.

Wir empfehlen die bewährte Methode, Links zu Workflowläufen und relevanten Artefakten in die PR unter einem Abschnitt "Nachweise" aufzunehmen, damit Prüfer ergebnisse schnell überprüfen können.

- name: Upload test results
  uses: actions/upload-artifact@v4
  with:
    name: test-results
    path: results/

Zuverlässigkeit setzt Fehler voraus.

Zuverlässige Systeme gehen davon aus, dass ein Fehler auftritt. Agents werden Vorgänge falsch verstehen, Tests fehlschlagen, und Änderungen führen zu Konflikten mit vorhandenem Verhalten. Ihre Architektur sollte Fehler frühzeitig erkennen und sichere Wiederherstellungspfade bereitstellen.

Ein praktisches Zuverlässigkeitsmuster umfasst:

  • Wiederholungen: Der Agent kann Verzweigung aktualisieren, wenn Prüfungen fehlschlagen.

  • Eskalation: Dauerhafte Fehler werden zusammengefasst und an einen Menschen weitergegeben.

  • Rollbackbereitschaft: Änderungen mit hohem Risiko umfassen Rollbacknotizen und Umfangsbeschränkungen.

Richtlinie für sichere Iteration

Verwenden Sie eine vorhersagbare Richtlinie für die Iteration:

  • Wenn eine erforderliche Prüfung fehlschlägt, kann der Agent den PR-Branch überarbeiten und die Prüfungen erneut ausführen.

  • Wenn dieselbe erforderliche Prüfung zweimal fehlschlägt, an einen menschlichen Prüfer eskalieren mit:

    • Was fehlgeschlagen hat

    • was versucht wurde,

    • welche Beweise vorhanden sind, und

    • Was der vorgeschlagene nächste Schritt ist.

Diese Richtlinie verhindert endlose Schleifen und macht Fehler umsetzbar.

Observability als erforderliche Architekturfunktion

Ein mindester Feststellbarkeitssatz für autonome Arbeit sollte Folgendes umfassen:

  • ein sichtbares Planartefakt,

  • PR + Commit-Verlauf

  • Links für Workflow-Läufe bei erforderlichen Prüfungen

  • dauerhafte Artefakte (Protokolle/Berichte/Ablaufverfolgungen),

  • Ergebnisse und Genehmigungen überprüfen.

Nachweise für ausführungs- und Codestatus nachverfolgbar machen

Unterrichten Sie ein Benennungs-/Metadatenprinzip:

  • Nachweise sollten auf einen bestimmten Workflow und einen bestimmten Commit nachverfolgt werden können.

Dies hilft beim Überprüfen und Debuggen, da Sie beantworten können: "Welche Ausführung hat dieses Artefakt produziert und mit welchem Codestatus?"

Teilen von Beweisen zur aufgabenübergreifenden Verwendung von Artefakten

Lehren Sie das Muster:

  • Artefakte dort hochladen, wo sie erstellt werden

  • Laden Sie sie dort herunter, wo sie überprüft oder bereitgestellt werden.

Dadurch bleiben die Ausgaben prüfbar und verwendbar, ohne dass generierte Dateien wieder in das Repository übertragen werden.

So steuern Sie Tools, MCP-Integrationen und geheime Schlüssel sicher

Die Agentprofilkonfiguration bietet drei Arten von Steuerelementen:

  • Funktionsgrenze: Welche Tools zulässig sind (Allowlists bevorzugen)
  • Sichtbarkeitsgrenze: Gibt an, ob der Agent in interaktiver Benutzeroberfläche ausgewählt werden kann.
  • Delegierungsgrenze: Welche Subagenten aufgerufen werden können und wie Übergaben erfolgen. Gestaltungshinweise:
  • Schreibgeschützte Toolsets für die Planung und Evaluierung von Agenten verwenden.
  • Beschränken Sie Implementierungstools auf Ausführungs-Agents.
  • Behandeln von Änderungen an Tool-Positivlisten als governance-sensible Änderung.

MCP-Server: Sicheres Erweitern von Tools

MCP-Server erweitern die Toolfunktion. Lehren Sie diese Muster:

  • Transport-Shape: einige MCP-Server sind Remoteendpunkte; andere sind lokale Prozesse.
  • Authentifizierung: Token müssen zur Laufzeit über geschützte Sicherheitsgrenzen eingefügt werden.
  • Namespace-Steuerelement: Die Aktivierung einer schmalen Tooluntermenge anstelle von breiten Wildcards bevorzugen.

Betriebsleitfaden:

  • Das Hinzufügen oder Erweitern von MCP-Tools erhöht den Auswirkungsbereich und soll wie eine Abhängigkeit mit hohem Risiko behandelt werden.

Einschränkungen für Geheimnisse und Umgebung (Geheimnisse aus den Repository-Inhalten heraushalten)

Platzieren Sie Geheimnisse nicht in:

  • Anleitungsdateien,
  • zugesicherte Konfigurationsdateien,
  • oder Workflow-YAML in Klartext.

Stattdessen:

  • Geschützte geheime Grenzen verwenden, die für die Laufzeiteinfügung vorgesehen sind,
  • Übergeben Sie geheime Schlüssel nur an die Komponenten, die sie benötigen,
  • Die Geheimnutzung (z. B. nach Umgebung) beschränken, um die Exposition zu verringern.

Lehren Sie das Prinzip:

  • Die Laufzeitumgebung des Agents hat eine eigene Sicherheitsgrenze; nehmen Sie nicht an, dass sie automatisch CI-Geheimnisse des Repositorys erbt.

So erzwingen Hooks Leitplanken und Audit-Protokollierung

In GitHub Copilot Agents werden Hooks als konfigurationsdateien definiert, die im Repository gespeichert sind (z. B. unter github/hooks/). Jeder Hook gibt an, wann und welche Aktion er ausführt.

Hooks führen benutzerdefinierte Befehle an bestimmten Punkten während der Agentausführung aus. Auf diese Weise können Teams Richtlinien erzwingen, Aktionen überprüfen und Überwachungsdaten automatisch erfassen.

Ein vereinfachtes Beispiel:

{
  "name": "block-high-risk-command",
  "trigger": "pre-tool-use",
  "run": "if [[ \"$TOOL\" == \"delete\" ]]; then echo 'Blocked unsafe command'; exit 1; fi"
}

So funktioniert's

  • Der Hook wird ausgeführt, bevor ein Tool ausgeführt wird (vor der Nutzung des Tools)

  • Die angeforderte Aktion wird überprüft.

  • Wenn die Aktion mit einem blockierten Muster übereinstimmt, wird die Ausführung beendet.

Häufige Hook-Muster

  • Voraktions-Hooks Überprüfen oder Blockieren unsicherer Aktionen vor der Ausführung

  • Hooks nach Aktionen Protokollierung von Toolnutzung, Ausgaben oder Entscheidungen für die Auditierung.

  • Error-Hooks erfassen Fehler und lösen eine Eskalation oder Warnung aus.

Welche Funktionen bieten Hooks?

  • Erzwingen von Sicherheitsrichtlinien (z. B. Blockieren unsicherer Befehle)

  • Hinzufügen von Überwachungsprotokollen für Compliance und Debugging

  • Integration in externe Systeme (Warnungen, Überwachung, Genehmigungen)

  • Hooks stellen durchsetzbare Kontrollpunkte bereit, die unabhängig von der Begründung des Modells funktionieren. Anstatt sich auf Anweisungen zu verlassen, stellen sie sicher, dass bestimmte Regeln während der Ausführung immer angewendet werden.

Wie Sie Zuverlässigkeit durch den Einsatz von Wiederholungsversuchen, Eskalationen und minimalen Berechtigungen gestalten

Wie wir bereits darüber gesprochen haben, werden Agenten schließlich scheitern, aber wir können Systeme erstellen, die diese Fehler erfassen und sicherstellen können, dass menschliche Interventionen sie einfangen, z. B. hier sind einige Möglichkeiten, um sicherzustellen, dass Fehler abgefangen werden:

  • Begrenzte Wiederholungsversuche für vorübergehende Fehler

  • Eskalationspfade für wiederholte Fehler

  • Rollback-Bereitschaft für hochriskante Änderungen

  • Berechtigungen mit minimalem Privileg, um den Auswirkungsbereich zu verringern

Rollbacksicheres Muster zum Unterrichten:

  • Explizite Verweise (Commit/Tag) bei der Bereitstellung vertraulicher Konfigurationen verwenden, anstelle des „neuesten einer Verzweigung”.

Erinnerung an das Prinzip der minimalen Rechte

  • Beschränken Sie Workflowberechtigungen standardmäßig, und erhöhen Sie nur bei Bedarf.

Berechtigungen für den Workflow mit Minimalberechtigungen

Die geringsten Berechtigungen verringern das Risiko, wenn ein Fehler auftritt. Darüber hinaus wird verhindert, dass eine überberechtigte Automatisierung zu einer architekturbedingten Sicherheitslücke wird.

permissions:
  contents: read
  pull-requests: write

Diese Konfiguration ermöglicht es der Automatisierung, Repository-Inhalte zu lesen und den PR-Kontext (Kommentare, Status) zu aktualisieren, während gleichzeitig standardmäßig umfassender Schreibzugriff verhindert wird.