0Pricing
AI Agents · Aula

Agentes programados e baseados em Cron

APScheduler, tarefas do cron e execução autônoma de agentes acionada por horários.

Agentes programados e baseados em Cron é uma aula grátis de AI Agents no CoddyKit. Esta é a aula 3 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de AI Agents, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Agents inclui 4 aulas no total.

Por que agendar agentes?

Algumas tarefas de agentes não precisam ser executadas continuamente nem sob demanda — elas são executadas conforme um agendamento. Relatórios diários, resumos semanais, verificações de dados a cada hora e limpezas periódicas são bons candidatos a agentes agendados.

Noções básicas do APScheduler

O APScheduler (Agendador Avançado do Python) executa trabalhos dentro do seu processo Python. Ele oferece três tipos de gatilho: date (uma vez), interval (repetição) e cron (baseado no calendário).

from apscheduler.schedulers.blocking import BlockingScheduler
from apscheduler.schedulers.background import BackgroundScheduler
from datetime import datetime

# BlockingScheduler: takes over the main thread
# BackgroundScheduler: runs in background thread

scheduler = BackgroundScheduler()

def my_agent_job():
    print(f'Agent running at {datetime.now()}')

# Add a simple interval job
scheduler.add_job(my_agent_job, 'interval', minutes=5)

scheduler.start()
print('Scheduler started in background')

# Your app continues running here
import time
time.sleep(15)
scheduler.shutdown()
print('Scheduler stopped')

Sintaxe do gatilho cron

O gatilho cron usa campos de cron conhecidos: year, month, day, week, day_of_week, hour, minute, second. Você pode usar números, intervalos, listas e curingas.

from apscheduler.schedulers.background import BackgroundScheduler

scheduler = BackgroundScheduler()

def morning_briefing():
    print('Good morning! Running daily briefing agent')

def weekly_report():
    print('Running weekly summary')

def every_business_hour():
    print('Hourly check during business hours')

# Every day at 9:00 AM
scheduler.add_job(morning_briefing, 'cron', hour=9, minute=0)

# Every Monday at 8:30 AM
scheduler.add_job(weekly_report, 'cron', day_of_week='mon', hour=8, minute=30)

# Every hour from 9am to 5pm, weekdays only
scheduler.add_job(every_business_hour, 'cron',
    day_of_week='mon-fri',
    hour='9-17',
    minute=0
)

scheduler.start()
print('Jobs scheduled:', len(scheduler.get_jobs()))

Sintaxe de expressões cron

As expressões cron padrão usam 5 campos: minute hour day month weekday. O APScheduler também aceita esses campos como uma única string com CronTrigger.from_crontab().

  • 0 9 * * * — diariamente às 9h
  • 0 9 * * 1 — toda segunda-feira às 9h
  • */15 * * * * — a cada 15 minutos
from apscheduler.schedulers.background import BackgroundScheduler
from apscheduler.triggers.cron import CronTrigger

scheduler = BackgroundScheduler()

def agent_task():
    print('Running scheduled agent')

# From crontab string: every day at 9am
trigger = CronTrigger.from_crontab('0 9 * * *')
scheduler.add_job(agent_task, trigger)

# Equivalent explicit form
scheduler.add_job(
    agent_task,
    'cron',
    minute=0,
    hour=9
)

# Every 15 minutes
scheduler.add_job(agent_task, CronTrigger.from_crontab('*/15 * * * *'))

print('Scheduled jobs:')
for job in scheduler.get_jobs():
    print(f'  {job.id}: next run {job.next_run_time}')

Gatilho de intervalo

O gatilho de intervalo executa um trabalho a cada N unidades de tempo. Use-o para consultas periódicas, sinais de atividade ou qualquer tarefa que deva se repetir com uma frequência fixa.

from apscheduler.schedulers.background import BackgroundScheduler
from datetime import datetime, timedelta

scheduler = BackgroundScheduler()

def check_for_updates():
    print(f'Checking for updates at {datetime.now()}')
    # Agent logic: poll API, check for new items

# Every 30 minutes
scheduler.add_job(check_for_updates, 'interval', minutes=30)

# Every 2 hours, starting 10 minutes from now
start_time = datetime.now() + timedelta(minutes=10)
scheduler.add_job(
    check_for_updates,
    'interval',
    hours=2,
    start_date=start_time
)

# Run once in the future (date trigger)
from apscheduler.triggers.date import DateTrigger
run_at = datetime.now() + timedelta(minutes=5)
scheduler.add_job(check_for_updates, DateTrigger(run_date=run_at))

scheduler.start()
print('All jobs scheduled')

Parâmetros e identificadores de trabalhos

Atribua um ID a cada trabalho para poder referenciá-lo, pausá-lo ou removê-lo posteriormente. Passe argumentos à função do trabalho por meio de args ou kwargs.

from apscheduler.schedulers.background import BackgroundScheduler

scheduler = BackgroundScheduler()

def fetch_report(report_type, user_id):
    print(f'Fetching {report_type} report for user {user_id}')

# Named job with arguments
scheduler.add_job(
    fetch_report,
    'cron',
    hour=9,
    minute=0,
    id='daily_report_user_42',
    kwargs={'report_type': 'daily', 'user_id': 42},
    replace_existing=True  # Update if job already exists
)

scheduler.start()

# Pause a specific job
scheduler.pause_job('daily_report_user_42')
print('Job paused')

# Resume it
scheduler.resume_job('daily_report_user_42')
print('Job resumed')

# Remove it
scheduler.remove_job('daily_report_user_42')
print('Job removed')

Persistência de trabalhos entre reinicializações

Por padrão, o APScheduler armazena os trabalhos na memória, e eles são perdidos ao reiniciar. Use o armazenamento de trabalhos do SQLAlchemy para persistir os trabalhos em um banco de dados, de modo que sobrevivam às reinicializações.

from apscheduler.schedulers.background import BackgroundScheduler
from apscheduler.jobstores.sqlalchemy import SQLAlchemyJobStore
from apscheduler.executors.pool import ThreadPoolExecutor

jobstores = {
    'default': SQLAlchemyJobStore(url='sqlite:///jobs.sqlite')
}

executors = {
    'default': ThreadPoolExecutor(20)
}

scheduler = BackgroundScheduler(
    jobstores=jobstores,
    executors=executors
)

def persistent_agent():
    print('Running persisted scheduled agent')

# This job survives restarts
scheduler.add_job(
    persistent_agent,
    'cron',
    hour=8,
    minute=0,
    id='morning_agent',
    replace_existing=True
)

scheduler.start()
print('Scheduler started with SQLite persistence')

Tratamento de exceções de trabalhos

Envolva as funções de trabalhos agendados em try/except para impedir que uma execução com falha interrompa silenciosamente as execuções futuras. Registre as falhas e, opcionalmente, envie alertas.

import logging
from apscheduler.schedulers.background import BackgroundScheduler
from apscheduler.events import EVENT_JOB_EXECUTED, EVENT_JOB_ERROR

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger('scheduler')

scheduler = BackgroundScheduler()

def job_listener(event):
    if event.exception:
        logger.error(f'Job {event.job_id} failed: {event.exception}')
        # Optionally send alert: email, Slack, PagerDuty
    else:
        logger.info(f'Job {event.job_id} completed successfully')

scheduler.add_listener(job_listener, EVENT_JOB_EXECUTED | EVENT_JOB_ERROR)

def my_agent_job():
    # Errors here are caught by the listener
    raise ValueError('Something went wrong in the agent')

scheduler.add_job(my_agent_job, 'interval', seconds=10, id='test_job')
scheduler.start()

Impedindo a sobreposição de trabalhos

Se um trabalho demorar mais do que seu intervalo, a próxima execução poderá começar antes que a anterior termine. Defina max_instances=1 (o padrão) ou use o agrupamento para ignorar execuções perdidas.

from apscheduler.schedulers.background import BackgroundScheduler
import time

scheduler = BackgroundScheduler()

def slow_agent():
    print('Agent started')
    time.sleep(45)  # Takes 45 seconds
    print('Agent finished')

# max_instances=1: only one run at a time (default)
# coalesce=True: if multiple runs were missed, fire only once when caught up
scheduler.add_job(
    slow_agent,
    'interval',
    minutes=1,
    max_instances=1,
    coalesce=True,
    id='slow_agent'
)

scheduler.start()
print('Slow agent scheduled (max 1 concurrent run)')

Integração do agendamento com o FastAPI

Use o BackgroundScheduler do APScheduler dentro do FastAPI com o contexto de lifespan para iniciar e parar o agendador corretamente junto ao ciclo de vida do servidor.

from fastapi import FastAPI
from apscheduler.schedulers.background import BackgroundScheduler
from contextlib import asynccontextmanager

scheduler = BackgroundScheduler()

def morning_agent_job():
    print('Morning agent running')

@asynccontextmanager
async def lifespan(app: FastAPI):
    # Start scheduler when app starts
    scheduler.add_job(morning_agent_job, 'cron', hour=9, minute=0)
    scheduler.start()
    print('Scheduler started')
    
    yield  # App runs here
    
    # Stop scheduler when app shuts down
    scheduler.shutdown()
    print('Scheduler stopped')

app = FastAPI(lifespan=lifespan)

@app.get('/jobs')
def list_jobs():
    return [
        {'id': job.id, 'next_run': str(job.next_run_time)}
        for job in scheduler.get_jobs()
    ]

Agendamento com reconhecimento de fuso horário

Sempre especifique os fusos horários dos agentes agendados. Os trabalhos do cron sem contexto de fuso horário podem ser executados em horários incorretos após mudanças no horário de verão.

from apscheduler.schedulers.background import BackgroundScheduler
import pytz

# Scheduler with timezone
scheduler = BackgroundScheduler(timezone='America/New_York')

def ny_morning_agent():
    print('Running at 9am New York time')

def london_eod_agent():
    print('Running at 5pm London time')

# 9am New York (handles EST/EDT automatically)
scheduler.add_job(
    ny_morning_agent,
    'cron',
    hour=9,
    minute=0,
    timezone=pytz.timezone('America/New_York')
)

# 5pm London time
scheduler.add_job(
    london_eod_agent,
    'cron',
    hour=17,
    minute=0,
    timezone=pytz.timezone('Europe/London')
)

scheduler.start()
print('Timezone-aware scheduler running')

Verificação de conhecimentos: agendamento

Teste sua compreensão do APScheduler e dos agentes baseados em cron.

Práticas recomendadas de agendamento

Regras fundamentais para agentes agendados confiáveis:

  • Sempre use agendamento com reconhecimento de fuso horário
  • Persista os trabalhos em um banco de dados para que sobrevivam às reinicializações
  • Defina max_instances=1 para trabalhos de longa duração
  • Adicione ouvintes de erros para detectar falhas silenciosas
  • Registre cada execução agendada com a hora de início, a hora de término e o resultado

Perguntas Frequentes

A aula “Agentes programados e baseados em Cron” é grátis?

Sim — o texto completo de “Agentes programados e baseados em Cron” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de AI Agents, atualize para CoddyKit PRO. O curso de AI Agents inclui 4 aulas no total.

O que vou aprender em “Agentes programados e baseados em Cron”?

APScheduler, tarefas do cron e execução autônoma de agentes acionada por horários. Você pratica AI Agents com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar AI Agents?

Nenhuma experiência prévia é necessária. AI Agents no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 3 de 4.

Quanto tempo leva a aula “Agentes programados e baseados em Cron”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de AI Agents?

Sim. Cada aula de AI Agents inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Padrões de agentes baseados em gatilho e ação
  2. Conectando agentes a webhooks
  3. Agentes programados e baseados em Cron
  4. Construindo um pipeline de automação entre vários aplicativos
← Voltar para AI Agents