Blog · Guia · 28 de outubro de 2026

Rode um agente agendado com o AEGIS: agendamentos, execuções e o que você vê quando uma falha

Também em: English, Español, 日本語 · Todos os guias em português

Aviso: a 100monkeys.ai desenvolve o AEGIS, então leia este guia como o relato de quem o fabrica. Ele foi redigido por um dos nossos agentes de IA a partir da documentação pública do AEGIS, principalmente a página Schedules e a referência Schedule Tools, e revisado pela empresa; esta versão em português é uma tradução do guia original em inglês. Cada campo, rota e mensagem é citado dessas páginas, em inglês e com a tradução ao lado. Não rodamos estas chamadas para este guia e, onde a documentação deixa um passo em aberto, dizemos isso.

AEGIS by 100monkeys.ai, in beta, é um orquestrador auto-hospedado que roda agentes autônomos em ambientes isolados e com políticas aplicadas. Este guia coloca um dos seus agentes num timer, lê o que cada disparo fez e mostra os quatro resultados que um disparo pode ter, para que uma execução que não aconteceu fique tão visível quanto uma que aconteceu.

O que é um agendamento

A documentação define em uma frase: "A schedule starts one of your agents or workflows as you, either once at a time you choose or again and again on a recurrence." (Um agendamento inicia um dos seus agentes ou workflows em seu nome, uma vez no horário que você escolher ou repetidamente segundo uma recorrência.) Daí saem três consequências, e cada uma molda os passos abaixo.

• Um agendamento é um objeto seu, "never a field of the agent or workflow it runs" (nunca um campo do agente ou workflow que ele roda).
• Ele roda como uma pessoa. "A schedule always runs as a person. A service account, or an operator acting for no person, cannot make, change, pause, resume, run or delete one." (Um agendamento sempre roda como uma pessoa. Uma conta de serviço, ou um operador que não age por nenhuma pessoa, não pode criá-lo, alterá-lo, pausá-lo, retomá-lo, rodá-lo nem apagá-lo.)
• Cada disparo é uma execução comum. "At each fire the orchestrator starts the run exactly as aegis.task.execute or aegis.workflow.run would for you, with the schedule's intent, input and connections." (A cada disparo o orquestrador inicia a execução exatamente como aegis.task.execute ou aegis.workflow.run fariam por você, com a intenção, a entrada e as conexões do agendamento.)

Passo 1. Escolha o agente e o horário

Use um agente que você já rodou uma vez à mão com aegis task execute <AGENT>, para saber como é uma boa execução.

Depois escolha um de dois horários. Você informa exatamente um deles.

• Uma vez: at, um horário RFC 3339 "at least one minute from now and at most a year ahead" (pelo menos um minuto a partir de agora e no máximo um ano à frente).
• Recorrente: recurrence com cron, timezone e jitter_seconds. O cron tem cinco campos (minuto, hora, dia do mês, mês, dia da semana), "no seconds field and no @daily-style shorthand" (sem campo de segundos e sem atalhos no estilo @daily). O fuso horário é um nome IANA e o padrão é UTC. O jitter atrasa cada execução por um valor aleatório de até esse número de segundos, no máximo 3600.

Dois limites para planejar: "A schedule runs at most once every 5 minutes" (um agendamento roda no máximo uma vez a cada 5 minutos), e você pode ter no máximo 25 agendamentos não apagados.

Passo 2. Escolha o que a execução pode alcançar

Uma execução agendada só alcança as conexões que o seu profile ou os seus contexts nomeiam, e "a schedule with neither reaches none of your connections" (um agendamento sem nenhum dos dois não alcança nenhuma das suas conexões). Um agendamento leva um ou outro, nunca os dois. Se o seu agente lê e-mail ou um repositório, nomeie o perfil agora; senão o disparo será recusado por falta de conexão, e a recusa dirá isso.

Passo 3. Crie o agendamento

Não existe comando de shell aegis schedule na CLI Reference. Você cria um agendamento com a rota REST POST /v1/schedules (escopo schedule:write), com a ferramenta MCP aegis.schedule.create ou pela página Schedules no Zaru. A ferramenta recebe estes argumentos, como a referência os lista:

aegis.schedule.create {
  "name": "Morning inbox triage",
  "target_kind": "workflow",
  "target": "email-inbox-triage",
  "intent": "Sort the new mail",
  "input": { "mailbox": "ann@example.com" },
  "recurrence": { "cron": "*/30 * * * *", "timezone": "UTC", "jitter_seconds": 300 }
}

Esse exemplo é o agendamento da própria documentação. Troque target_kind para agent e target para o nome do seu agente. A resposta é {"schedule": {...}} com o seu state, next_run_at e last_run. Leia next_run_at antes de sair.

Passo 4. Dispare uma vez, agora

Não espere o primeiro horário agendado para saber se funciona. O dono pode iniciar uma execução imediata com POST /v1/schedules/{id}/run ou aegis.schedule.run_now. Ela roda "exactly as a fire starts it: as the owner, with the schedule's target, input, connections or profile, and attachments" (exatamente como um disparo a inicia: como o dono, com o alvo, a entrada, as conexões ou o perfil e os anexos do agendamento), e "nothing else changes" (nada mais muda): o agendamento mantém o estado e o horário.

Passo 5. Leia as execuções

aegis.schedule.runs { "schedule_id": "<id>", "limit": 20 }

A rota é GET /v1/schedules/{id}/runs?limit=. As execuções vêm da mais nova para a mais antiga, cada uma com o seu scheduled_time (null para uma execução iniciada agora), fired_at, outcome, detail e execution (o seu id, kind e status). Leve o id da execução para a CLI para ler a execução em si: aegis task logs <EXECUTION_ID>, com --errors-only quando quiser só as falhas.

Passo 6. Conheça os quatro resultados

Cada disparo é registrado uma vez por horário agendado, então um disparo que o Temporal repete "answers the first fire's record instead of starting a second run" (responde com o registro do primeiro disparo em vez de iniciar uma segunda execução). Cada registro tem um resultado:

• started: a execução começou, e o disparo registra o id dela.
• skipped_overlap: "The run the previous fire started is still running, so this fire starts nothing." (A execução que o disparo anterior iniciou ainda está rodando, então este disparo não inicia nada.) O Zaru mostra como "Skipped: the last run was still running".
• skipped_paused: o agendamento está pausado.
• refused: "The run could not start. The fire records the refusal's sentence, for example a required connection that was not chosen." (A execução não pôde começar. O disparo registra a frase da recusa, por exemplo uma conexão necessária que não foi escolhida.)

Um resultado started diz que a execução começou, não que deu certo. O status da execução está em execution.status, e o motivo de uma falha, nos logs dela.

Passo 7. O que acontece quando os disparos continuam falhando

"When the last three fires of a recurring schedule were all refused, the schedule pauses itself, with the reason 'Paused after three runs could not start: <the last refusal>.'" (Quando os três últimos disparos de um agendamento recorrente foram recusados, o agendamento se pausa sozinho, com esse motivo.) Leia paused_reason no agendamento, corrija a causa e retome com aegis.schedule.resume. Um disparo perdido enquanto o orquestrador reinicia "is still made up to 10 minutes late; later than that, the time is skipped" (ainda é recuperado com até 10 minutos de atraso; depois disso, o horário é pulado).

Passo 8. As aprovações continuam valendo

Uma execução agendada age em seu nome, "so every tool call that waits for your approval in a conversation waits for it in a scheduled run too" (então toda chamada de ferramenta que espera a sua aprovação numa conversa também espera numa execução agendada). No Zaru o pedido aparece na página Approvals como "From your schedule <name>".

O que a documentação deixa em aberto

• Um comando de shell. A CLI Reference não lista subcomando de agendamento, então quem se auto-hospeda usa as rotas REST ou um cliente MCP.
• Quem é "você" no stack local. Agendamentos rodam como uma pessoa e precisam de schedule:write, enquanto o stack do aegis init roda sem IAM. A documentação não diz de quem é um agendamento ali; não testamos.

Próximos passos

Para colocar uma pessoa entre o agente agendado e tudo o que ele envia, leia Como dar a um orquestrador uma etapa de aprovação. Para ler o que uma execução fez, leia Como ler o log de uma execução do AEGIS.

Instale o AEGIS pelo 100monkeys.ai