Transforme um agente em um serviço, não em um terminal esquecido.

Empacote o worker

Use um runtime suportado, dependências fixadas e um gerenciador de serviços ou contêiner. Configure limites de reinício e um usuário de serviço dedicado. Mantenha as credenciais privadas do fornecedor em configuração protegida fora dos arquivos públicos da aplicação.

Guarde o progresso antes de as ações importarem

Use uma fila ou banco de dados durável para as tarefas. Atribua um identificador de operação exclusivo, registre solicitações externas e reconcilie resultados incertos. Uma reinicialização não deve enviar um segundo e-mail, criar um segundo pedido ou cobrar duas vezes.

Adicione observabilidade útil

Monitore a conclusão das tarefas, a idade da fila, a taxa de erros e o custo, em vez de verificar apenas se um processo existe. Mantenha os logs pequenos o suficiente para revisão e oculte tokens, prompts e documentos que não precisam ser retidos.

Defina um limite claro

Limite o gasto com modelos, a concorrência do navegador, o tempo de execução e o número de tentativas. Mantenha um interruptor de pausa fácil e um caminho de revisão humana para ações consequentes. Um worker menor e bem observado é mais fácil de confiar do que um sem restrições.

Utilize um supervisor e um agendamento deliberado

O Systemd e o Docker são formas comuns de manter um processo ativo após a desconexão do terminal. Para um serviço systemd, Type=exec pode reportar falhas de execução de forma mais direta do que um simples lançamento em segundo plano, e Restart=on-failure pode reiniciar falhas com uma política limitada. As tarefas agendadas devem evitar execuções sobrepostas. Mantenha explícitos o diretório de trabalho, o utilizador do serviço e o ambiente. O exemplo pressupõe que o utilizador koala-agent, o ambiente virtual, o módulo worker e o ficheiro de ambiente privado já existem; adapte-os antes de instalar uma unit.

• Use uma conta de serviço dedicada
• Defina um atraso de reinicialização e um limite de falhas
• Verifique o estado da tarefa anterior antes de iniciar uma execução agendada

[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

Documentação oficial: Semântica de serviço do systemd

Defina um orçamento diário e um limite de duplicidade

Defina para o worker um número máximo de pedidos, um limite de gastos e um tempo limite de execução. Utilize um registo de idempotência durável para ações que afetam o mundo exterior. Um clique bem-sucedido no navegador pode ocorrer antes de o processo receber uma resposta; inspecione o estado externo antes de tentar novamente. As montagens de segredos do Docker Compose podem manter um segredo fora da imagem, mas as permissões e a aplicação consumidora ainda precisam de revisão.

Documentação oficial: Segredos do Docker Compose

Defina uma política explícita de recuperação para uma tarefa periódica

Use um serviço de longa duração para um worker de fila persistente e um serviço oneshot acionado por temporizador para uma tarefa agendada limitada. Com um temporizador de calendário systemd, Persistent=true pode acionar uma ativação perdida após uma paragem; não recria todo um atraso de negócio. Decida se essa recuperação é desejável. RandomizedDelaySec pode distribuir os arranques, enquanto um lease ao nível da aplicação impede que duas réplicas processem o mesmo trabalho agendado.

• Registe o fuso horário pretendido e inspecione os próximos horários de execução antes de ativar a programação.
• Mantenha o prazo de execução da tarefa menor que um intervalo que não deve se sobrepor, ou use uma concessão durável com expiração e propriedade.
• Faça com que a tarefa selecione o trabalho pendente a partir do estado armazenado, em vez de assumir que todos os eventos de temporizador anteriores foram executados.
• Verifique a versão do systemd instalada antes de usar uma diretiva do manual mais 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

Documentação oficial: systemd: agendamento por timer

Distinga um ciclo de falhas de um worker bloqueado

Uma política de reinício pode recuperar um processo com falha, mas repetir uma credencial inválida ou uma migração quebrada a cada poucos segundos torna a falha mais ruidosa. Limite as inicializações do serviço e alerte sobre falhas repetidas. Um processo ativo também pode ficar travado: meça a idade da tarefa mais antiga e da última operação concluída. Teste uma indisponibilidade do API, um disco vazio e uma parada de processo com tarefas descartáveis, depois verifique se o estado durável evita ações externas duplicadas.

• Defina um orçamento de provedor e um tempo limite de solicitação na aplicação, bem como um limite de CPU/memória no runtime.
• Contêineres Docker não têm um limite de memória útil específico da carga de trabalho só porque são contêineres; configure e teste os limites deliberadamente.
• Armazene um segredo fora da imagem e da árvore pública, depois teste se os logs de falhas e os diagnósticos o ocultam.
• Mantenha uma via de paragem manual e exija revisão adequada para gastos, escritas em produção ou mensagens externas.

Documentação oficial: systemd: supervisão de serviços · Docker: restrições de recursos de contêiner