Controlla e gestisci agenti: osservabilità, strumenti, MCP, segreti, ganci e affidabilità

  • 5 minuti

In questa unità si apprenderà quanto segue:

  • Individuare le prove e gli artefatti necessari per il lavoro dell'agente

  • Come controllare gli strumenti, le integrazioni MCP e i segreti in modo sicuro

  • Come gli hook applicano barriere di sicurezza e registrazione dei log di controllo

  • Come progettare per garantire l'affidabilità utilizzando ritentativi, gestione delle escalation e il principio dei privilegi minimi

Evidenza e artefatti necessari per gli agenti

Un sistema agente deve produrre artefatti visibili per ogni azione significativa. Senza artefatti, non è possibile esaminare in modo affidabile il comportamento, gli errori di debug o eseguire analisi post-hoc.

In GitHub, l'osservabilità viene ottenuta tramite artefatti come:

  • richieste pull e sequenze temporali delle richieste pull,

  • commit e cronologia dei rami,

  • esecuzioni del flusso di lavoro e log dei processi,

  • verifiche richieste e risultati dell'analisi

  • artefatti del flusso di lavoro caricati (ad esempio, report di test).

Set di osservabilità minimo

Un'attività dell'agente ben progettata deve produrre prove visibili e verificabili usando elementi nativi GitHub:

  • un piano strutturato, in genere incluso nella descrizione o nella discussione di una pull request

  • una richiesta pull limitata e una cronologia di commit

  • link alle esecuzioni del flusso di lavoro per i controlli necessari

  • artefatti caricati (ad esempio, log o report)

  • esaminare i risultati (approvazioni o modifiche richieste)

Caricare gli artefatti del flusso di lavoro per la revisione e il debug

Il caricamento degli artefatti rende l'evidenza durevole e verificabile, anche quando i log scorrono.

Raccomandiamo di includere collegamenti alle esecuzioni del flusso di lavoro e agli artefatti pertinenti nella pull request in una sezione "Evidenza", in modo che i revisori possano convalidare rapidamente i risultati.

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

L'affidabilità presuppone un errore

I sistemi affidabili presuppongono che si verifichi un errore. Gli agenti incomprenseranno le attività, i test avranno esito negativo e le modifiche saranno in conflitto con il comportamento esistente. L'architettura deve rilevare gli errori in anticipo e fornire percorsi di ripristino sicuri.

Un modello di affidabilità pratico include:

  • Ritenti: l'agente può aggiornare il ramo quando i controlli falliscono.

  • Escalation: gli errori persistenti vengono riepilogati e trasmessi a un essere umano.

  • Prontezza al rollback: le modifiche ad alto rischio includono le note di rollback e i limiti dell'ambito.

Criteri di iterazione sicuri

Usare criteri prevedibili per l'iterazione:

  • Se un controllo obbligatorio ha esito negativo, l'agente può modificare il ramo PR ed eseguire di nuovo i controlli.

  • Se lo stesso controllo richiesto fallisce due volte, si dovrebbe procedere a un'escalation coinvolgendo un revisore umano:

    • cosa non ha funzionato

    • ciò che è stato tentato,

    • quali prove esistono, e

    • qual è il passaggio successivo suggerito.

Questo criterio consente di evitare cicli infiniti e rende gli errori interattivi.

Osservabilità come funzionalità architetturale richiesta

Un set minimo di osservabilità per il lavoro autonomo deve includere:

  • un artefatto visibile del progetto

  • richiesta pull + cronologia dei commit

  • collegamenti di esecuzione del flusso di lavoro per i controlli necessari,

  • artefatti durevoli (registri/rapporti/tracce)

  • esaminare i risultati e le approvazioni.

Rendere l'evidenza tracciabile per l'esecuzione e lo stato del codice

Insegnare un principio riguardante la denominazione e i metadati:

  • La prova deve essere tracciabile a una specifica esecuzione del flusso di lavoro e a uno specifico commit.

Ciò consente di controllare e eseguire il debug: è possibile rispondere a "quale esecuzione ha prodotto questo artefatto e rispetto allo stato del codice?"

Condividere l'evidenza tra processi usando artefatti

Insegnare il modello:

  • Caricare gli artefatti in cui vengono prodotti

  • Scaricali laddove vengono esaminati o distribuiti.

In questo modo gli output vengono controllati e utilizzabili senza eseguire il commit dei file generati nel repository.

Come controllare gli strumenti, le integrazioni MCP e i segreti in modo sicuro

La configurazione del profilo agente offre tre tipi di controllo:

  • Limite di funzionalità: quali strumenti sono consentiti (preferenza per gli elenchi consentiti)
  • Limite di visibilità: se l'agente è selezionabile dall'utente nell'interfaccia utente interattiva
  • Limite di delega: quali subagenti possono essere invocati e come avvengo i passaggi, linee guida per la progettazione.
  • Usare strumenti di sola lettura per la pianificazione e la revisione degli agenti.
  • Limitare gli strumenti di implementazione agli agenti di esecuzione.
  • Considerare le modifiche apportate agli elenchi consentiti degli strumenti come modifica sensibile alla governance.

Server MCP: estendere gli strumenti in modo sicuro

I server MCP estendono la funzionalità degli strumenti. Insegnare questi modelli:

  • Forma trasporto: alcuni server MCP sono endpoint remoti; altri sono processi locali.
  • Autenticazione: i token devono essere inseriti in fase di esecuzione attraverso barriere segrete protette.
  • Controllo dello spazio dei nomi: preferire l'abilitazione di un subset di strumenti ristretto anziché caratteri jolly estesi.

Linee guida operative:

  • L'aggiunta o l'espansione degli strumenti MCP aumentano il raggio di esplosione e devono essere esaminate come una dipendenza ad alto rischio.

Segreti e vincoli di ambiente (mantenere i segreti fuori dal contenuto del repository)

Non inserire segreti in:

  • file di istruzioni,
  • file di configurazione commitati
  • o flusso di lavoro YAML in testo normale.

Invece:

  • Usare i limiti dei segreti protetti destinati all'inserimento in fase di runtime,
  • Passare segreti solo ai componenti che ne hanno bisogno,
  • Definire l'ambito della disponibilità dei segreti (ad esempio, in base all'ambiente) per ridurre l'esposizione.

Insegnare il principio:

  • "L'ambiente di runtime dell'agente ha un proprio limite segreto; non presupporre che eredita automaticamente i segreti CI del repository."

Come gli hook applicano protezioni e registrazione di controllo

In GitHub Copilot agenti gli hook vengono definiti come file di configurazione archiviati nel repository (ad esempio, in .github/hooks/). Ogni hook specifica quando viene eseguito e l'azione eseguita.

Gli hook eseguono comandi personalizzati in punti specifici durante l'esecuzione dell'agente. In questo modo i team possono applicare criteri, convalidare le azioni e acquisire automaticamente i dati di controllo.

Esempio semplificato:

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

Come funziona

  • L'hook viene eseguito prima dell'esecuzione di uno strumento (pre-uso dello strumento)

  • Controlla l'azione richiesta

  • Se l'azione corrisponde a un modello bloccato, l'esecuzione viene arrestata

Modelli di hook comuni

  • Hook pre-azione Verificano o bloccano azioni pericolose prima dell'esecuzione

  • Hook post-azione Registra l'utilizzo, gli output, o le decisioni per audit

  • Error hooks Catturare i fallimenti e attivare l'escalation o gli avvisi

Quali hook abilitare

  • Applicazione dei criteri di sicurezza (ad esempio, blocco di comandi non sicuri)

  • Aggiunta di log di controllo per la conformità e il debug

  • Integrazione con sistemi esterni (avvisi, monitoraggio, approvazioni)

  • Gli hook forniscono punti di controllo applicabili che operano indipendentemente dal ragionamento del modello. Anziché basarsi sulle istruzioni, assicurarsi che determinate regole vengano sempre applicate durante l'esecuzione.

Come progettare per garantire l'affidabilità utilizzando ritentativi, gestione delle escalation e il principio dei privilegi minimi

Come discusso in precedenza, gli agenti falliranno inevitabilmente, ma possiamo creare sistemi in grado di rilevare questi fallimenti e garantire che l'intervento umano li intercetti. Ad esempio, ecco alcuni modi per assicurarsi che i fallimenti vengano rilevati:

  • Tentativi limitati per i guasti temporanei

  • Percorsi di escalation per errori ripetuti

  • Preparazione al rollback per le modifiche ad alto rischio

  • Autorizzazioni con privilegi minimi per ridurre il raggio di esplosione

Modello di rollback sicuro da insegnare:

  • Usare riferimenti espliciti (commit/tag) quando si distribuisce la configurazione sensibile, anziché "più recente in un ramo".

Promemoria dei privilegi minimi:

  • Limitare le autorizzazioni del flusso di lavoro per impostazione predefinita ed elevare solo se necessario.

Autorizzazioni del flusso di lavoro con privilegi minimi

Il privilegio minimo riduce il rischio quando si verifica un errore. Impedisce inoltre che l'automazione con autorizzazioni eccessiva diventi una vulnerabilità dell'architettura.

permissions:
  contents: read
  pull-requests: write

Questa configurazione consente all'automazione di leggere il contenuto del repository e aggiornare il contesto PR (commenti, stati), impedendo, per impostazione predefinita, l'accesso in scrittura generale.