AI Task Scheduler — Guia do usuário | YoBench

Para que serve o módulo «AI Task Scheduler»

O AI Task Scheduler executa o assistente de IA num agendamento. Você define um prompt, escolhe um provedor e um contexto, anexa um conjunto opcional de ferramentas e diz ao agendador quando rodar — a cada minuto, hora, dia, semana ou mês. O assistente executa de forma autônoma; se ele montar um plano marcado como perigoso, a execução pausa com um aviso claro Approve / Deny (Aprovar / Negar) em vez de falhar.

O que você obtém:

• Execuções de IA orientadas por cron — cinco tipos de agendamento (minuto, hora, dia, semana, mês).
• Execuções manuais sob demanda — Run Now (Executar agora) em qualquer tarefa.
• Isolamento por tarefa — cada tarefa escolhe seu próprio provedor, contexto, system prompt, temperatura, máximo de iterações e ferramentas permitidas.
• Fluxo de aprovação — planos perigosos são salvos como pending_approval para você revisar antes que a execução continue.
• Linha do tempo ao vivo — mensagens em tempo real e resultados das ferramentas durante a execução.
• Histórico de execuções com status, tipo de gatilho, duração, tokens e custo.
• Cancelamento por escopo — cada execução tem uma chave de escopo única; ferramentas de longa duração são limpas quando você cancela.

Conceitos

Tipos de agendamento

Os agendamentos são guardados como schedule_type mais campos auxiliares e traduzidos para uma expressão cron na hora.

Gatilhos manuais (Run Now) ignoram o agendamento.

Controle de ferramentas

Cada tarefa pode:

• Rodar com todas as ferramentas disponíveis (tarefas legadas / novas onde tools_enabled está ligado e a lista de ferramentas está vazia/null), ou
• Rodar com uma whitelist — escolha os IDs exatos das ferramentas que o assistente pode chamar (busca web, automação de navegador, terminal, sistema de arquivos, ferramentas de documento, etc.), ou
• Rodar com ferramentas totalmente desativadas — o assistente só tem o prompt e o contexto.

Esse é o principal botão para uma tarefa agendada segura: uma tarefa de relatório diário provavelmente não precisa de acesso ao terminal; uma tarefa de code-review pode querer só web e browser.

Fluxo de aprovação

A pipeline roda em modo autônomo — todo plano que não esteja marcado como perigoso executa sem perguntar. Quando o assistente emite um plano com requiresConfirmation = true:

1. A execução transita para pending_approval.
2. O plano é persistido; a execução fica pausada.
3. A UI mostra o plano com dois botões: Approve (Aprovar) e Deny (Negar).
4. Approve — a pipeline retoma do ponto salvo.
5. Deny — a execução termina com status cancelled e o motivo "Rejected by user".

Aprovações pendentes aparecem tanto na visualização da execução quanto numa lista dedicada Pending Approvals (Aprovações pendentes) no topo da página, para não se perderem.

Ciclo de vida de uma execução

agendamento dispara (ou Run Now)
        │
        ▼
   cria a execução
   status = running
        │
        ▼
  ─── mensagens entram na linha do tempo ───
        │
        ├─ done            → status = done
        ├─ error           → status = error  (mensagem de erro salva)
        ├─ usuário cancela → status = cancelled
        └─ plano perigoso  → status = pending_approval
                                  │
                                  ├─ approve → status = running → continua
                                  └─ deny    → status = cancelled

Cada execução registra: gatilho, timestamps de início/fim, duração, uso de tokens, custo em dólares, mensagem de erro (se houver) e o log completo de mensagens.

Configurações

Uma tarefa é criada em Scheduler → Create, que abre o drawer do formulário. Campos:

• Title (Título) — nome de exibição.
• Prompt — a instrução principal que o assistente roda em cada tick.
• System Prompt — papel / comportamento persistente opcional. Vazio por padrão.
• Provider (Provedor) — o provedor de IA usado pela execução.
• Context (Contexto) — contexto RAG opcional injetado na execução.
• Temperature (Temperatura) — 0.0 – 1.0, padrão 0.3.
• Max auto-iterations (Máx. de iterações automáticas) — limite de rodadas de uso de ferramentas em uma execução, padrão 5.
• Schedule type (Tipo de agendamento) + os campos correspondentes de hora / dia da semana / dia.
• Is active (Ativa) — toggle para pausar o agendamento sem apagar a tarefa.
• Tools enabled (Ferramentas ativadas) — on/off global do toolset.
• Allowed tools (Ferramentas permitidas) — multi-select usado quando as ferramentas estão ativadas.

O formulário também consegue salvar um rascunho da tarefa sem ativá-la.

Fluxo de uso

1. Crie uma tarefa agendada

1. Abra o Scheduler na barra lateral.
2. Clique em Create (Criar) → o drawer da tarefa desliza para dentro.
3. Preencha o título, o prompt e escolha um provedor.
4. (Opcional) anexe um contexto, ajuste o system prompt, baixe a temperatura.
5. Escolha o tipo de agendamento e o horário.
6. Escolha a política de ferramentas: ativadas + whitelist, ativadas + livre, ou desativadas.
7. Ative Is active (Ativa) e salve.

2. Execute sob demanda

• Abra a tarefa → Run Now (Executar agora) → a execução aparece na linha do tempo na hora.
• Acompanhe ao vivo as mensagens e os resultados das ferramentas.
• Pare a qualquer momento com Stop (Parar) — o escopo é cancelado e as ferramentas de longa duração são derrubadas.

3. Trate uma aprovação pendente

1. Ou o badge da execução fica amarelo (pending), ou a lista Pending Approvals mostra um item novo.
2. Abra a execução → revise o plano proposto.
3. Approve — a execução retoma. Deny — a execução é cancelada.

4. Revise o histórico

• A visualização da tarefa lista cada execução com status, gatilho, duração, uso de tokens e custo.
• Clique numa execução para abrir o log completo de mensagens e qualquer saída das ferramentas.
• Erros incluem a mensagem completa; cancelamentos registram quem / o que cancelou.

Dicas e limitações

• Use execuções manuais para testar um prompt antes de ativar o agendamento.
• Mantenha o system prompt específico da tarefa — a persona global pertence às configurações do AI Chat.
• Os números de tokens / custo vêm da resposta do provedor; para modelos locais self-hosted o custo aparece como zero.
• O agendador roda dentro do app desktop — quando o YoBench está fechado o cron não dispara. Planeje considerando isso ou mantenha o app aberto na bandeja.
• Comece com max auto-iterations conservador; aumente quando confiar no prompt.

Próximos passos

• Conecte um provedor de IA e ao menos um contexto.
• Combine uma tarefa agendada com o DB Manager — por exemplo, uma execução noturna que resuma os logs de slow query.
• Para trabalho periódico não baseado em IA (cron puro + scripts), use as DB tasks embutidas ou o módulo Cenários.

Ajuda e feedback

Encontrou um bug ou quer um novo tipo de agendamento? Escreva para nós pelo formulário de contato.