Rendi un agente un servizio, non un terminale dimenticato.

Prepara il worker

Usa un runtime supportato, dipendenze con versione fissata e un gestore di servizi o un container. Configura limiti di riavvio e un utente di servizio dedicato. Conserva le credenziali private del fornitore in una configurazione protetta al di fuori dei file pubblici dell'applicazione.

Salva i progressi prima che le azioni contino

Usa una coda o un database durevole per i job. Assegna un identificatore di operazione univoco, registra le richieste esterne e riconcilia gli esiti incerti. Un riavvio non dovrebbe inviare una seconda email, creare un secondo ordine o addebitare due volte.

Aggiungi un'utile osservabilità

Monitora il completamento dei job, l'età della coda, il tasso di errori e il costo invece di controllare solo se un processo esiste. Mantieni i log abbastanza piccoli da poter essere esaminati e oscura token, prompt e documenti che non devono essere conservati.

Imposta un limite chiaro

Limita la spesa per i modelli, la concorrenza del browser, il tempo di esecuzione e il numero di tentativi. Mantieni un interruttore di pausa facile da usare e un percorso di revisione umana per le azioni con conseguenze. Un worker più piccolo e ben monitorato è più facile da fidarsi rispetto a uno senza restrizioni.

Usa un supervisore e una pianificazione ben ponderata

Systemd e Docker sono modi comuni per far sopravvivere un processo alla disconnessione del terminale. Per un servizio systemd, Type=exec può segnalare un errore di esecuzione in modo più diretto rispetto a un semplice avvio in background, e Restart=on-failure può riavviare gli errori con una policy limitata. I job pianificati dovrebbero evitare esecuzioni sovrapposte. Mantieni espliciti la directory di lavoro, l'utente del servizio e l'ambiente. L'esempio presuppone che l'utente koala-agent, l'ambiente virtuale, il modulo worker e il file di ambiente privato esistano già; adattali prima di installare un'unità.

• Usa un account di servizio dedicato
• Imposta un ritardo di riavvio e un limite di errori
• Controlla lo stato del job precedente prima di avviare un'esecuzione pianificata

[Unit]
Description=Example agent worker
After=network-online.target

[Service]
Type=exec
User=koala-agent
WorkingDirectory=/opt/koala-agent
EnvironmentFile=/etc/koala-agent.env
ExecStart=/opt/koala-agent/.venv/bin/python -m worker
Restart=on-failure
RestartSec=10
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target

Documentazione ufficiale: Semantica del servizio systemd

Imposta un budget giornaliero e un limite per i duplicati

Assegna al worker un numero massimo di richieste, un limite di spesa e un timeout di esecuzione. Usa un record di idempotenza durevole per le azioni che influiscono sul mondo esterno. Un clic riuscito nel browser può avvenire prima che il processo riceva una risposta; ispeziona lo stato esterno prima di riprovare. I mount dei secret di Docker Compose possono tenere un secret fuori dall'immagine, ma i permessi e l'applicazione che lo consuma richiedono comunque una revisione.

Documentazione ufficiale: Segreti di Docker Compose

Assegna a un job periodico una politica di recupero esplicita

Usa un servizio a esecuzione prolungata per un worker di coda persistente e un servizio oneshot attivato da timer per un'attività pianificata limitata. Con un timer di calendario systemd, Persistent=true può attivare un'attivazione persa dopo un fermo; non ricrea un intero arretrato operativo. Decidi se questo recupero è desiderabile. RandomizedDelaySec può distribuire gli avvii, mentre un lease a livello applicativo impedisce a due repliche di elaborare lo stesso lavoro pianificato.

• Registra il fuso orario previsto e controlla i prossimi orari di esecuzione prima di attivare la pianificazione.
• Mantieni la scadenza di esecuzione dell'attività più breve di un intervallo che non deve sovrapporsi, oppure usa un lease durevole con scadenza e proprietà.
• Fai in modo che il job selezioni il lavoro in sospeso dallo stato memorizzato invece di presumere che ogni precedente evento timer sia stato eseguito.
• Controlla la versione di systemd installata prima di usare una direttiva del manuale più recente.

# Read-only checks after creating your own matching units.
systemctl list-timers --all
systemctl status koala-agent.service
journalctl -u koala-agent.service --since today --no-pager

Documentazione ufficiale: systemd: pianificazione dei timer

Distingui un ciclo di crash da un worker bloccato

Una politica di riavvio può recuperare un processo fallito, ma ripetere ogni pochi secondi una credenziale non valida o una migrazione rotta rende un guasto più rumoroso. Limita gli avvii del servizio e avvisa in caso di errore ripetuto. Un processo attivo può anche essere bloccato: misura l'età del job più vecchio e dell'ultima operazione completata. Prova un'interruzione di API, un disco vuoto e un arresto del processo con job usa e getta, poi verifica che lo stato durevole impedisca azioni esterne duplicate.

• Imposta un budget del provider e un timeout delle richieste nell'applicazione, oltre a un limite di CPU/memoria sul runtime.
• I container Docker non hanno un limite di memoria utile specifico per il carico di lavoro solo perché sono container; configura e verifica i limiti deliberatamente.
• Archivia un segreto fuori dall'immagine e dall'albero pubblico, poi verifica che i log di crash e la diagnostica lo oscurino.
• Mantieni una via di arresto manuale e richiedi una revisione adeguata per spese, scritture in produzione o messaggi esterni.

Documentazione ufficiale: systemd: supervisione dei servizi · Docker: vincoli sulle risorse dei container