Tutorial DeepSeek Superagent: osserva la CI e autorizza una fix

Che cos'è DeepSeek Superagent?

DeepSeek Superagent osserva un repository GitHub tramite DeepSeek Harness. Le regole del team decidono se un evento merita lavoro; il lavoro accettato va in una sessione separata. Questo tutorial copre il prototipo pubblicato, non idee solo di design.

Harness fornisce il runtime; Superagent aggiunge monitoraggio degli eventi e autorizzazione. Il nostro approfondimento su agent harness tratta strumenti, memoria e controllo.

Come funziona DeepSeek Superagent?

Un nuovo evento GitHub può attraversare quattro fasi. Queste fasi tengono separate la decisione e il cambio di codice:

• Sorgente e Trigger: il polling di GitHub trasforma ogni evento in un Trigger su un'Issue, una pull request o main.

• Ammissione: il gate lo etichetta come richiesta esplicita, candidato inferito o niente.

• Valutazione e Decisione:  la CI inferita è giudicata rispetto alle regole. Una richiesta esplicita viene instradata a una Decisione di accettazione, motivo explicitRouted.

• Ticket ed Executor: il lavoro accettato ottiene la sua autorizzazione, la sessione del worker e la directory.

Un commento successivo sul Thread del Ticket stesso arriva al suo worker senza una nuova Valutazione. Il diagramma mostra tre percorsi GitHub: CI del branch predefinito, una richiesta esplicita e la relativa revisione. All'interno del percorso CI, osserva e auto-lancia una regola corrispondente in punti diversi.

La CI viene giudicata. Le richieste avviano il lavoro. Immagine dell'Autore.

Qual è la differenza tra modalità osservazione e modalità automatica?

La modalità di accettazione si applica solo al lavoro che Superagent ha inferito da un evento. Scegli una di tre impostazioni:

• off scarta i candidati inferiti.

• observe li valuta ma registra un esito positivo come "accetterei".

• auto avvia il lavoro dopo una valutazione positiva.

Una richiesta da parte di una persona autorizzata funziona in ogni modalità e crea il proprio Ticket. Mantieni auto disattivato per questo tutorial.

Crea un workflow di riparazione CI in modalità osservazione

La pipeline usa pytest e due job GitHub Actions per trasformare gli eventi in ricavi giornalieri. Superagent inserisce una decisione prima dell'inizio del lavoro. Il nostro tutorial su Claude Code Routines tratta un altro workflow event-driven.

Traccia il bug di replay nei ricavi giornalieri

Il bug conta due volte un pagamento ripetuto. Ogni riga ha un event_id, order_id, timestamp e un importo. Un ordine può contenere più pagamenti validi.

Ecco perché il dedup su order_id può superare un test di replay ma eliminare pagamenti reali; la chiave corretta è event_id. Calcola i totali attesi con il modulo csv di Python prima di autorizzare l'agente, così l'output dell'agente non è la soluzione.

Definisci una riparazione CI riuscita

Il successo dipende da ciò che fa il workflow, non solo da ciò che dice l'agente. Imposta queste condizioni prima di modificare il repository:

• Ignorare un errore solo di documentazione.

• Riconoscere revenue-integrity senza avviare il lavoro.

• Aprire una pull request solo dopo una richiesta esplicita.

• Preservare le asserzioni e superare una suite di holdout preconfezionata.

Prepara la suite di holdout prima che Superagent ottenga l'accesso. Questo mantiene il comportamento atteso fuori dagli input di sviluppo del worker.

Prerequisiti e isolamento di DeepSeek Superagent

Ti serve una chiave API DeepSeek, due account GitHub e un ambiente Linux usa e getta. Per le basi di Harness, vedi la nostra guida di base all'installazione.

Software e account necessari

Blocca le versioni software in modo che un aggiornamento non possa cambiare il workflow. L'ultima colonna registra la configurazione usata per i risultati più avanti nell'articolo:

L'agente ha bisogno di un proprio utente GitHub con accesso in scrittura perché Superagent legge le notifiche di quell'account. Aggiungi all'elenco degli autorizzati solo i manutentori umani che possono autorizzare il lavoro.

Isola l'agente dai file personali

Entrambi i preset danno all'utente del sistema operativo pieno accesso e il wrapper gh non isola il processo. Usa una distribuzione WSL nuova con automount e interop disattivati:

Se hai già una macchina virtuale Linux usa e getta, salta il blocco WSL e usa quella. Tieni credenziali e file non correlati fuori.

# /etc/wsl.conf inside the disposable distribution
[automount]
enabled = false
mountFsTab = false
[interop]
enabled = false
appendWindowsPath = false
[user]
default = superagentOfferto da

Un utente dedicato superagent dovrebbe contenere solo la chiave DeepSeek e il token dell'agente. Questo riduce gli accessi accidentali ma non è un confine di sicurezza; il modello di sicurezza WSL di Microsoft consiglia una macchina virtuale separata fuori da WSL per codice non fidato.

Su GitHub, proteggi main con una pull request obbligatoria, almeno un'approvazione indipendente e entrambi i check di CI. Dai all'agente accesso in scrittura senza bypass da amministratore. Nulla di tutto ciò impedisce il prompt injection tramite testo nelle Issue.

Passo 1: Crea la pipeline di ricavi in Python e la baseline CI

Il repository del tutorial pubblicato ora ha la correzione fusa su main, quindi non usare il branch attuale come stato iniziale. Usa questi commit per separare le tre fasi:

La pipeline e i test sotto sono semplificati dalla baseline verde (a6d2036), non presi dall'attuale main. Crea un repository usa e getta da quel commit prima di seguire i passi di CI:

git clone https://github.com/KhalidAbdelaty/superagent-revenue-lab.git revenue-lab
cd revenue-lab
git switch -C main a6d2036
git remote remove origin

export EXPERIMENT_REPO="YOUR_LOGIN/superagent-revenue-lab"
gh repo create "$EXPERIMENT_REPO" --private --source=. --remote=origin --pushOfferto da

Usa questo nuovo repository per gli errori controllati e i branch dell'agente. Lascia il repository pubblicato invariato; i suoi commit di incidente e soluzione sono riferimenti per il confronto.

"""Daily revenue report built from payment events."""
import pandas as pd


def load_events(path):
    """Read payment events; amounts are integer cents."""
    return pd.read_csv(path, parse_dates=["occurred_at", "received_at"])


def daily_revenue(events):
    """Return one row per UTC day with total revenue in cents."""
    days = events["occurred_at"].dt.strftime("%Y-%m-%d")
    report = (
        events.assign(day=days)
        .groupby("day", as_index=False)["amount_cents"]
        .sum()
        .rename(columns={"amount_cents": "revenue_cents"})
    )
    return reportOfferto da

Il dataset di base copre due giorni e include più pagamenti reali per un ordine. Pytest controlla i totali noti e quel caso di ordine condiviso, e per ora nulla testa i replay:

import pandas as pd


def test_daily_totals_match_known_values():
    report = daily_revenue(load_events(DATA))
    assert report["revenue_cents"].tolist() == [20398, 27550]


def test_events_on_the_same_order_are_all_counted():
    t = pd.Timestamp(0, unit="s", tz="UTC")
    events = pd.DataFrame({
        "event_id": ["evt_a", "evt_b"],
        "order_id": ["ord_1", "ord_1"],
        "occurred_at": [t, t],
        "received_at": [t, t + pd.Timedelta(seconds=1)],
        "amount_cents": [1000, 250],
    })
    assert daily_revenue(events)["revenue_cents"].tolist() == [1250]Offerto da

Dai a ogni job il nome del comportamento che verifica. Gli stessi nomi appariranno poi in GitHub e nel testo del Trigger di Superagent:

name: ci
on:
  push:
    branches: [main]
  pull_request:

jobs:
  revenue-integrity:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install -r requirements.txt   # pandas==2.3.3, pytest==8.4.2
      - run: pytest -v

  docs-check:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: python scripts/check_docs.py      # fails if README links a missing fileOfferto da

Se il semplice pytest non riesce a importare revenue, aggiungi un pytest.ini con pythonpath = .. Conferma che entrambi i job passano su main prima di installare Superagent.

La directory pubblicata experiment/holdout documenta l'esecuzione originale ma è visibile nel clone pubblico. Per un nuovo esperimento, crea una suite fresca fuori da ogni checkout e filesystem leggibile dal worker.

Fai l'hash di quella suite prima di inviare la richiesta di riparazione. Copri questi casi:

• Consegne ripetute di un evento.
• Eventi diversi con lo stesso ID ordine.
• Un DataFrame di input che deve restare invariato.
• Le colonne e l'ordinamento attesi in output.

Tieni nascosta questa suite fino alla revisione. Il Passo 6 la esegue dall'ambiente umano separato dopo che il worker ha finito.

Il seguente diagramma separa gli input di sviluppo del worker dal controllo finale del manutentore.

I dati di holdout restano fuori dal worker. Immagine dell'Autore.

Passo 2: Installa DeepSeek Superagent e collega GitHub

Installa il bundle in un profilo Harness dedicato, separato dal profilo usato per il lavoro quotidiano. Carica il token dell'account dell'agente in AGENT_GH_TOKEN senza scriverlo nel repository. Quindi esegui questi comandi come utente superagent:

npm install -g @deepseek-ai/[email protected] [email protected]

git clone https://github.com/deepseek-ai/dsh-superagent-prototype.git ~/dsh-superagent
cd ~/dsh-superagent
git checkout --detach 8c32a9dc5d72c033816c6a8110b37f40cf94fba4
pnpm install && pnpm build

# A gh wrapper that only ever sees the agent account
mkdir -p "$HOME/.local/bin"
export PATH="$HOME/.local/bin:$PATH"
cat > ~/.local/bin/gh-agent <<'W'
#!/bin/sh
GH_CONFIG_DIR="$HOME/.config/gh-agent" exec gh "$@"
W
chmod +x ~/.local/bin/gh-agent
printf '%s' "$AGENT_GH_TOKEN" | gh-agent auth login --hostname github.com --with-token
gh-agent api user --jq .login            # your dedicated agent account

# Dedicated profile, then the bundle
dsh superagent --from-default-profile web --dump-config > /dev/null
dsh plugin --profile superagent add "link:$PWD"Offerto da

Nota: le esecuzioni in questo tutorial hanno usato il commit 6337fc8, che DeepSeek ha poi squashato in 8c32a9d.

Usa l'esempio di profilo nel repository clonato per impostare una directory di stato e legare il pannello a 127.0.0.1:3082. Poi avvia il servizio in tmux:

scripts/dsh-superagent start
scripts/dsh-superagent statusOfferto da

Questo profilo separa i riavvii del servizio dalle sessioni personali di Harness. Mantiene anche PATH e impostazioni Git del plugin fuori dal profilo normale.

status può riportare setup in sospeso o repositoryUnset finché non salvi la Sorgente GitHub nel Passo 3. A questo punto, conferma solo che il runtime risponde e che il pannello Superagent si apre; non aspettarti ancora una Sorgente o una baseline CI.

Apri Settings → Models nel profilo dedicato e seleziona deepseek-flash. In Superagent → Settings → Eval ed Execution, conferma che entrambi i ruoli ereditano quel modello del profilo o indica esplicitamente deepseek-flash.

Passo 3: Configura il monitoraggio di GitHub Actions in modalità osservazione

Lascia l'osservazione della CI del branch predefinito disattivata mentre salvi Sorgente, policy, regola e impostazioni dell'executor. Attivala solo dopo che il nuovo repository ha un main verde, in modo che la prima lettura registri una baseline pulita.

Configura la Sorgente GitHub

In Settings → Sources, imposta il repository su EXPERIMENT_REPO, punta il campo CLI al wrapper dedicato gh-agent e lascia spenta l'osservazione della CI del branch predefinito. Salva la Sorgente e attendi l'eventuale riavvio prima di cambiare la policy.

Configura la policy di ammissione della CI

Un risultato CI non ha mittente. La sua riga di ammissione ha una cella che di default è ignore. Se lasci quell'impostazione invariata, la Valutazione non vede mai la CI.

Definisci una regola ristretta per revenue-integrity

Sostituisci gli esempi di regole con una regola chiamata come il check. Indica all'evaluator di non indovinare le cause:

{
  "rules": [{
    "id": "revenue-integrity",
    "name": "Revenue integrity CI failures",
    "enabled": true,
    "instruction": "A default-branch CI result in which the check named revenue-integrity newly fails. That check executes the pytest suite guarding the daily revenue totals. Judge only from the check names and results you can read for that commit; do not guess a root cause. Failures limited to other checks, such as docs-check (README links), do not match. A recovery where every check passes does not match. Work, if accepted: investigate the failing revenue-integrity tests, fix the pipeline without weakening or deleting any assertion, add a regression test, and open a pull request for human review. Never merge."
  }],
  "sources": {"github": {
    "allowed": [{"id": "<human-login>"}],
    "bots": [],
    "admission": {"ci": {"unlistedUnaddressed": "inferred"}}
  }}
}Offerto da

Aggiungi un comando di preparazione che crea un worktree Git per ogni Ticket. Ogni worker parte così da un checkout del repository:

C=/home/superagent/src/superagent-revenue-lab
git -C $C fetch --no-tags "https://github.com/$DSH_SUPERAGENT_GITHUB_REPOSITORY.git" \
  "${DSH_SUPERAGENT_GITHUB_PR_HEAD:-HEAD}:refs/dsh-superagent/$DSH_SUPERAGENT_TICKET" &&
git -C $C worktree add -b "agent/$DSH_SUPERAGENT_NAME" "$DSH_SUPERAGENT_DIR" "refs/dsh-superagent/$DSH_SUPERAGENT_TICKET"Offerto da

Superagent compila queste variabili per ogni Ticket. Controlla che la directory risultante contenga l'aspettato checkout prima di autorizzare il lavoro.

L'helper di configurazione opzionale scrive la stessa Sorgente, policy, Eval ed executor. Tieni l'osservazione CI spenta nel primo passaggio; imposta sempre esplicitamente repository dell'esperimento e richiedente autorizzato:

export REPO="$EXPERIMENT_REPO"
export ALLOWED="YOUR_GITHUB_LOGIN"
bash /path/to/configure.sh allOfferto da

Mantieni disabilitata l'esecuzione proattiva

Mantieni Eval in observe con il modello predefinito del profilo. Dopo ogni evento, controlla la scheda Eval per la Decisione e la scheda Execution per eventuali Ticket.

Attiva l'osservazione CI e registra la baseline

Dopo che entrambi i job GitHub Actions passano su main, attiva l'osservazione della CI del branch predefinito. Con lo script helper, usa il suo secondo passaggio:

OBSERVE_CI=true bash /path/to/configure.sh source
bash /path/to/configure.sh showOfferto da

La prima lettura registra lo stato senza creare lavoro. Verifica tutte e quattro le condizioni:

• La configurazione non mostra requisiti in sospeso.

• La Sorgente GitHub riporta ready.

• La Sorgente registra una baseline CI pulita.

• Le schede Trigger ed Execution non mostrano Trigger o Ticket di baseline.

Se uno di questi controlli fallisce, fermati prima di creare l'errore di documentazione. Gli screenshot di Sorgente ed Eval mostrano la configurazione finale.

Card Sorgente GitHub con osservazione CI. Immagine dell'Autore.

Impostazioni Eval: una regola, modalità osservazione. Immagine dell'Autore.

Passo 4: Testa un errore non correlato in GitHub Actions

Usa un link rotto nel README come errore non correlato. Poiché il branch protetto rifiuta un check fallito, usa il bypass da amministratore umano solo in questo repository usa e getta; non darlo mai all'agente.

sed -i 's|^- Tests: .*|&\n- Data dictionary: [docs/data-dictionary.md](docs/data-dictionary.md)|' README.md
git commit -am "docs: link the data dictionary from the README" && git pushOfferto da

Al termine di GitHub Actions, docs-check è fallito e revenue-integrity è passato. Questo corrispondeva alla regola impostata: Superagent ha ignorato il candidato perché la regola sui ricavi non corrispondeva.

La Decisione ha usato ignoredFromCard, una scorciatoia per i candidati che non toccano una regola attiva. Quindi questo controllo riguarda l'instradamento, non la regola in sé.

Ripristina la modifica al README e attendi che entrambi i job passino. Superagent dovrebbe ignorare il ripristino e restare inattivo.

Passo 5: Attiva un errore CI di Revenue Integrity

Usa lo stesso percorso riservato agli umani per aggiungere i dati dell'incidente dal repository del tutorial. Questo riepilogo mostra il replay e i pagamenti separati su un ordine, senza le colonne dei timestamp:

event_id,order_id,amount_cents,delivery
evt_1009,ord_507,5000,first
evt_1010,ord_508,6400,first
evt_1011,ord_508,1600,first
evt_1009,ord_507,5000,replay
evt_1012,ord_509,2100,firstOfferto da

Il repository mantiene le colonne complete dei timestamp; qui sono omesse perché non decidono l'identità dell'evento. Il calcolo indipendente preparato in precedenza si aspetta 15.100 centesimi, quindi imposta quel valore nel test e aggiungi test_replayed_event_is_counted_once().

E       actual daily total: 20100
E       expected daily total: 15100
E       replay total: 8000 != 4000
FAILED tests/test_revenue.py::test_daily_totals_match_known_values
FAILED tests/test_revenue.py::test_replayed_event_is_counted_once
2 failed, 1 passedOfferto da

I 5.000 centesimi in più sono un pagamento contato due volte. Modificare 15100 in 20100 o cancellare il test di replay renderebbe verde la CI, ma nessuna delle due è una riparazione.

Il workflow GitHub Actions fallito mostra solo il fallimento di revenue-integrity. Il suo Trigger è arrivato dopo circa un intervallo di polling.

Eval ha segnato il candidato come "accetterei", mentre la scheda Execution è rimasta vuota. L'evaluator ha visto i nomi dei check e gli esiti, non il log di pytest, quindi sapeva quale guardia era fallita ma non il motivo.

La modalità osservazione registra solo "accetterei". Immagine dell'Autore.

Passo 6: Autorizza la correzione e verifica la pull request

Il percorso con richiesta esplicita descritto prima ora autorizza l'esecuzione. Le notifiche GitHub possono arrivare in ritardo.

Gestisci una menzione nell'Issue mancata

In Superagent 6337fc8, la Sorgente GitHub sovrappone i poll di cinque secondi e legge un thread notificato dal cursore successivo. Le notifiche di menzione arrivavano 21–23 secondi dopo, quindi un poll poteva avanzare oltre il messaggio.

Questa tempistica spiega perché il corpo della nuova Issue e alcuni commenti non sono mai diventati Trigger. Una segnalazione della community descrive la stessa modalità di errore.

Autorizza la correzione con un commento su GitHub

Pubblica di nuovo la richiesta come commento nuovo e conferma che appare il suo Trigger. Superagent dovrebbe accettarla come richiesta esplicita e avviare il worker.

La menzione nel commento crea il Ticket autorizzato. Immagine dell'Autore.

Controlla la correzione di deduplicazione degli eventi dell'agente

La pull request risultante ha basato la correzione su event_id. Rivedi il diff invece di affidarti alla descrizione:

 def daily_revenue(events):
     """Return one row per UTC day with total revenue in cents."""
+    # The payment webhook may deliver the same event more than once, with a
+    # different received_at but the same event_id. One event_id is one payment
+    # event, so keep only its first delivery before aggregating.
+    events = events.drop_duplicates(subset="event_id", keep="first")
     days = events["occurred_at"].dt.strftime("%Y-%m-%d")Offerto da

Ha aggiunto un test di replay e non ha cancellato nulla. Il primo comando di test è fallito perché mancavano le dipendenze. Dopo che il worker ha creato un ambiente virtuale, la suite di test visibile è passata.

Prova pagamenti che condividono un ordine

Richiedi modifiche senza menzionare l'agente: dimostra che due pagamenti su uno stesso ordine, identici tranne per event_id, contano entrambi, e che un replay di uno conta una volta. La revisione dovrebbe raggiungere lo stesso Ticket senza una nuova Valutazione.

Il worker ha risposto con un commit che ha solo aggiunto un test e lasciato invariata la pipeline. Prima dell'approvazione, controlla l'esatto head SHA e riesegui la suite indipendente contro quella revisione.

Il feedback della revisione continua lo stesso Ticket. Immagine dell'Autore.

Verifica la correzione con dati indipendenti

Esegui l'holdout dall'ambiente umano separato contro l'esatta testa della pull request. Su a43c541, entrambe le suite hanno passato 5 test su 5 senza rimuovere un'asserzione; 62bac08 ha mantenuto lo stesso tree.

I test scritti solo dall'agente coprono solo i casi scelti dall'agente.

Passo 7: Fai il merge della fix e misura il ripristino della CI

Dopo il merge, verifica che main torni verde e che il ripristino non avvii nuovo lavoro. Poi rivedi la traccia degli eventi, il tempo trascorso e il costo del provider.

Fai il merge della fix e conferma il ripristino della CI

Dopo approvazione manuale e merge, entrambi i check del branch predefinito sono passati. Superagent ha ignorato il ripristino, non ha avviato altro lavoro e ha chiuso il Ticket esistente con esito merged.

Valuta acquisizione eventi e decisioni

Segui ogni evento dall'acquisizione all'esito, come descritto nella nostra guida alla valutazione degli agenti AI. In tre ripetizioni, gli eventi arrivati a Eval hanno seguito il percorso atteso; le mancate acquisizioni sono avvenute in intake, non nella Decisione del modello.

Misura correttezza, tempo e costo della riparazione

Lo stesso scenario è stato eseguito in tre repository e distribuzioni WSL nuovi con Superagent 6337fc8, Harness 0.2.1-rc.3, deepseek-flash e un'unica policy. I costi usano la tariffa DeepSeek fuori picco più bassa; sono riproduzioni, non benchmark.

Tutte e tre le correzioni hanno usato event_id; ogni test di holdout è passato. L'acquisizione è variata di più: la menzione nel corpo dell'Issue è stata mancata ogni volta, e la terza riproduzione ha mancato anche due commenti prima che ne arrivasse uno.

La seconda riproduzione ha riscritto i commit e l'approvazione è arrivata prima del nuovo run di holdout. Il controllo successivo è passato, ma l'ordine più sicuro è head SHA, holdout, poi approvazione.

Limitazioni e troubleshooting di DeepSeek Superagent

Diversi errori qui sembrano silenzi, quindi inizia trovando dove si è fermato un evento. La parte frustrante è che una notifica mancata e un ignore corretto possono sembrare uguali.

Errori CI che non producono Trigger

Superagent traccia i cambiamenti nel set di fallimenti, quindi la lettura di baseline, un check che continua a fallire e i check ancora in esecuzione non producono nulla. Un Trigger senza Decisione di solito indica la cella di ammissione CI, non il modello.

Richieste GitHub che non arrivano mai

Le richieste possono fallire se il mittente non è autorizzato, la Sorgente è spenta, l'elaborazione è in pausa o GitHub notifica in ritardo. Se quei controlli passano, pubblica un commento nuovo; modificare il corpo dell'Issue non crea eventi.

Limiti della riparazione CI autonoma

Il prototipo non offre un confine di sicurezza. I worker hanno pieno accesso come utente OS e le regole di disclosure sono testo del prompt. Isola l'account agente e limitane l'uso al repository usa e getta.

Prima di passare a auto, raccogli settimane di Decisioni osservate, conta sia gli accettati sbagliati sia gli ignore sbagliati e sposta il worker da WSL a una macchina virtuale separata.

Considerazioni finali

Il contrasto iniziale ha retto: due stati CI in rosso non hanno portato alla stessa azione. Superagent ha ignorato docs-check e segnato revenue-integrity come "accetterei", mentre la modalità osservazione ha lasciato il codice intatto finché una persona non ha richiesto la riparazione.

La patch su event_id è stata lineare. L'acquisizione delle notifiche è stata meno affidabile: la menzione nel corpo dell'Issue non ha mai raggiunto Eval, quindi una regola corretta non poteva aiutare.

Non generalizzerei questo risultato alla riparazione CI autonoma. Il repository era piccolo, la regola ristretta e il merge controllato da umani. Altrove, parti da verde, ispeziona le Decisioni, autorizza esplicitamente, tieni i dati di holdout separati e fai il merge dopo controlli indipendenti.

Il mio prossimo passo sarebbe correggere il percorso di notifica GitHub e ripetere il workflow con più tipi di errore. Finché non esistono tali evidenze, terrei la modalità auto disattivata.