Tarefas agendadas

Uma tarefa agendada é uma mensagem que o seu agente manda para si mesmo num horário marcado. Este capítulo explica o que é uma delas, o que o painel Tarefas agendadas mostra a você e o fato incômodo sobre elas: ler tarefas funciona nos dois harnesses, mas criar, editar e excluir pela API é só do ganglion, e qualquer outro harness responde 501.

O que é uma tarefa agendada

Uma tarefa é um registro guardado: um nome, um agendamento e uma mensagem. Quando chega a hora, essa mensagem é repassada como um turno comum — o agente a lê, trabalha e escreve um transcript — e ninguém está esperando do outro lado. O resultado é guardado e lido depois no painel. Um disparo feito pelo agendador do próprio orquestrador, que é como o ganglion funciona, não é entregue a ninguém, e isso é proposital.

Existem três tipos de agendamento, e o painel nomeia cada um como o registro nomeia: uma expressão cron (Cron 0 7 * * 1), um intervalo que se repete (A cada 6h) ou um instante único (Uma vez em …). Uma tarefa também pode ser marcada para se remover depois de rodar, o que o painel mostra como “Se remove depois de executar”.

Isto é trabalho sem ninguém olhando. A mensagem é repassada a cada ocorrência, para sempre, sem ninguém lendo o resultado, e é por isso que o orquestrador a limita a 8 KiB e limita a trinta minutos um turno disparado.

O painel

Abra Tarefas agendadas na barra lateral e ele aparece ao lado da conversa, para você ler uma execução passada sem perder o chat em que está. O subtítulo dele declara o escopo com honestidade: “O que o agente executa em horários programados, e o que cada execução produziu. Somente leitura: peça ao agente para criar ou alterar uma tarefa.”

Cada tarefa mostra quando roda de novo, quando rodou pela última vez, se está desabilitada e para onde ela entrega, se o registro dela nomeia um destino. Abaixo dela ficam as execuções. Clicar numa delas abre o transcript daquela execução — as mensagens, as chamadas de ferramenta e os resultados delas — e Voltar às tarefas devolve você à lista.

Duas coisas sobre as execuções valem saber antes de você ler demais nelas:

• Só a execução mais recente de uma tarefa ativa registra um status. As execuções anteriores mostram quanto tempo levaram e quanto registraram, e nada mais. Não há marcas de sucesso ao lado delas porque o armazenamento não guarda um resultado por execução de onde desenhar uma.
• Uma execução pode sobreviver à tarefa dela. Uma tarefa que se remove depois de rodar deixa os transcripts para trás, então o painel agrupa esses sob “Tarefa removida” — a tarefa não está mais agendada, mas o trabalho que ela fez continua registrado.

O painel também oferece Ocultar concluídas, que dobra para fora as tarefas que já rodaram e não vão rodar de novo, uma atualização Buscar novas tarefas (o agente pode agendar algo entre duas visitas) e um controle Referenciar no chat em qualquer tarefa ou execução. Esse último joga a tarefa ou a execução no espaço de contexto do compositor, para você perguntar sobre ela na conversa ao lado sem copiar nada.

Quem pode criar uma, e onde

Esta é a parte que depende do harness do seu agente. Um harness é o programa dentro do container do agente que de fato roda o laço; os dois que este livro cobre são o picoclaw e o ganglion, e Harnesses explica como um deles é escolhido.

Ler funciona nos dois. Isso é proposital, e o próprio código do orquestrador diz por quê: esconder um agendamento que não vai disparar é estritamente pior do que mostrá-lo e dizer isso, porque uma tarefa que você não vê é uma tarefa que você não consegue parar. Então GET /v1/cron/tasks e GET /v1/cron/runs são atendidos seja qual for o harness, e não precisam de um container no ar.

Escrever é só do ganglion. POST, PATCH e DELETE em /v1/cron/tasks são recusados para qualquer outro harness com um 501, que o nomeia:

creating scheduled tasks over this API is not available on the
"picoclaw" harness (agent "beta"): its agent creates them itself

Isso não é um bug e não é um esboço. No picoclaw o agendamento vive em timers dentro do container, na memória do próprio agente, onde o orquestrador não os enxerga — então escrever o arquivo de jobs do picoclaw de fora produziria um registro que você lê e um timer que nunca mudou. Um 501 é pior de receber e muito melhor de depurar.

A razão de o ganglion poder ser escrito é a imagem espelhada. Ele não tem agendador nenhum; o orquestrador guarda o agendamento, num arquivo mantido acima do ponto de montagem do workspace do container, e dispara os jobs ele mesmo. Não há um segundo escritor para discordar. Manter esse arquivo fora do container também é uma propriedade de segurança: nada dentro do agente o alcança, então um turno conduzido por texto não confiável não consegue agendar os próprios turnos futuros.

O app web não escreve nem um nem outro. Seja como for que o seu agente esteja configurado, o painel hoje é somente leitura — a camada de servidor do app expõe só as duas rotas de leitura, e não há botão de criar em lugar nenhum do chat. Então, na prática:

Essa segunda linha é o estado honesto das coisas, e vale soletrar. Pedir a um agente ganglion que agende algo não vai funcionar: ele não alcança o armazenamento, e o guia do próprio workspace dele diz isso a ele — “Também não existe cron/: o seu trabalho agendado é guardado fora desta árvore, onde você não alcança.” O app web não tem controle de criar. E as rotas de escrita também não podem ser chamadas do navegador, porque o navegador guarda um cookie de sessão e nada mais: nenhum token, nenhum endereço de destino. As rotas estão construídas e o armazenamento está no lugar, mas a superfície que deixaria um membro chegar até elas não foi escrita.

A frase “peça ao agente” do painel descreve, portanto, o caso do picoclaw, e é o único pedaço da tela que ainda não distingue os dois harnesses.

O que a diferença custa a você de verdade

Se você só lê as suas tarefas, o harness quase não aparece. Onde ele aparece é em se o agendamento dispara ou não.

Um agendamento do picoclaw são timers no próprio processo, então um container parado não dispara nada. Num agente configurado para desligar quando fica ocioso, as tarefas são reais, aparecem listadas e são inertes — e o painel diz isso, em vez de deixar você supor que a tarefa rodou:

Estas tarefas não estão sendo executadas. Esta instância é desligada quando fica ociosa, e um agendamento só dispara enquanto ela está no ar. As tarefas abaixo continuam registradas — um administrador precisa mudar esta instância para contínua para que voltem a rodar.

Um agendamento do ganglion é guardado pelo orquestrador, que está sempre no ar e que liga o container para entregar o turno. Escalar a zero é exatamente o que aquele desenho tinha em mente, então o aviso nunca aparece para um agente ganglion.

Mais três propriedades do agendador do orquestrador valem saber, porque são escolhas e não acidentes:

• Um job é reivindicado antes de rodar, não registrado depois. Um orquestrador que morre no meio de um turno perde aquela execução, em vez de redisparar a cada arranque. Para trabalho sem ninguém olhando, um resumo diário perdido é uma lacuna; um redisparado é um agente fazendo trabalho de verdade duas vezes, sem ninguém vendo.
• Um agendamento atravessado por um cochilo dispara uma vez só. Repassar cada ocorrência perdida entregaria de uma vez um fim de semana de turnos de hora em hora.
• Dois turnos agendados nunca se sobrepõem num mesmo workspace. Um job que chega à hora enquanto outro seu está rodando fica pendente e é pego na passagem seguinte. As suas próprias mensagens não são afetadas em nenhuma das direções — uma execução agendada nem as bloqueia nem é bloqueada por elas.

Tarefas e projetos

As tarefas agendadas têm escopo como tudo mais num projeto: dentro de um projeto você vê as tarefas daquele projeto e nada mais, e fora de um você vê as tarefas que pertencem ao workspace do próprio agente. Agendamentos por projeto são algo que só o ganglion faz — no picoclaw os jobs de todos os projetos caem num repositório só, o que é uma limitação daquele harness e não uma decisão.

Uma consequência vale repetir do capítulo de projetos. Excluir um projeto derruba o roteamento dele, mas não os jobs agendados dele, então eles continuam disparando. Em vez de deixá-los ficar invisíveis, o orquestrador lista os jobs órfãos de um projeto excluído na lista de tarefas do próprio agente, onde você ainda consegue achá-los e pará-los.

Para onde ir agora

Harnesses explica a escolha em torno da qual este capítulo inteiro gira e por que uma chave harness: não declarada ainda significa picoclaw hoje. Trabalhando com projetos cobre o escopo, e o Guia de administração cobre o modo de instância que um administrador precisa mudar para fazer um agendamento do picoclaw disparar.