Agentes de Polling em Assistentes de IA: 11 Padrões de Implementação

Os agentes de polling (verificação periódica) são uma das partes menos glamourosas da arquitetura de assistentes de IA, mas também são uma das mais úteis.

Um assistente de chat normal espera que o usuário faça uma pergunta. Um agente de polling continua observando. Ele verifica uma fonte, percebe mudanças, decide se algo é relevante e, em seguida, age. Essa ação pode ser uma notificação, um resumo, um rascunho, uma chamada de ferramenta ou um fluxo de trabalho completo.

É assim que um assistente passa de “responder à minha pergunta” para “ficar de olho nisso para mim”. Em vez de ser reativo, ele se torna um processo em segundo plano que percebe coisas em nome do usuário e age quando as condições são atendidas.

O ponto de design importante é simples: não torne o modelo de linguagem responsável pelo tempo, estado, tentativas ou bloqueios. Use a infraestrutura de backend normal para isso. Use o modelo onde ele é valioso: interpretando contextos confusos, fazendo julgamentos semânticos e produzindo linguagem útil.

O que é um Agente de Polling?

Um agente de polling é um processo em segundo plano que verifica repetidamente uma fonte e aciona uma ação do assistente quando uma condição é atendida. Na stack mais ampla de Sistemas de IA — onde o assistente combina um LLM, memória, ferramentas, roteamento e observabilidade — a camada de polling é o que torna o assistente proativo em vez de puramente reativo. Para ver a visão completa das cinco camadas, consulte Arquitetura de Assistente de IA: LLM, Memória, Ferramentas, Roteamento, Observabilidade.

Exemplos:

• Verificar uma caixa de entrada todas as manhãs e resumir mensagens importantes.
• Observar uma lista de tarefas do Notion e executar o próximo item pendente.
• Monitorar uma issue do GitHub até que ela mude de status.
• Verificar um trabalho de IA de longa duração até que o resultado esteja pronto.
• Verificar um horário de reserva até que um se torne disponível.
• Observar um portal de fornecedores até que um documento apareça.
• Escanear novos artigos de pesquisa uma vez por semana e resumir os relevantes.

Um agente de polling prático tem cinco responsabilidades:

1. Acordar na hora certa.
2. Ler da fonte.
3. Lembrar do que já viu.
4. Decidir se o novo estado importa.
5. Agir uma vez, com segurança, sem se repetir.

Um fluxo de produção típico parece com isso:

agendador
  -> trabalhador de polling
  -> sistema de origem
  -> repositório de estado
  -> filtros determinísticos
  -> avaliação opcional de LLM
  -> ação do assistente

Esta estrutura é entediante da melhor maneira possível. Sistemas entediantes são mais fáceis de depurar às 2 da manhã.

O Estado que Todo Agente de Polling Precisa

Os agentes de polling precisam de estado durável. O histórico de conversação não é suficiente. O assistente pode lembrar da conversação, mas o sistema precisa de um registro operacional confiável.

Um bom registro de estado de polling geralmente contém:

{
  "poll_id": "poll_123",
  "user_id": "user_456",
  "source_type": "notion",
  "source_ref": "database_tasks",
  "condition": "pegar uma tarefa no estado Pendente e executá-la",
  "interval_seconds": 600,
  "last_run_at": "2026-06-19T01:00:00Z",
  "next_run_at": "2026-06-19T01:10:00Z",
  "last_seen_cursor": "cursor_or_timestamp",
  "last_result_hash": "b64e8a...",
  "failure_count": 0,
  "status": "active"
}

O esquema exato depende da fonte, mas a maioria dos sistemas precisa desses conceitos.

Definição de Polling

Isso descreve o que o agente está observando e por quê.

poll_id
user_id
workspace_id
source_type
source_ref
condition_text
priority
status

Por exemplo:

source_type: notion
source_ref: Banco de dados de Tarefas
condition_text: Encontrar uma tarefa Pendente, reivindicá-la, executá-la e marcá-la como Concluída.

Agendamento

Isso descreve quando o agente deve ser executado.

interval_seconds
cron_expression
timezone
last_run_at
next_run_at
jitter

Para um agente Hermes que verifica o Notion a cada 10 minutos:

interval_seconds: 600
timezone: Australia/Melbourne

Cursor ou Instantâneo

Isso ajuda o agente a evitar o reprocessamento dos mesmos dados.

Dependendo da fonte, isso pode ser:

last_seen_id
last_seen_timestamp
api_cursor
etag
version
content_hash

Para uma fila de tarefas do Notion, o cursor pode ser menos importante do que o status da tarefa e os campos de reivindicação. Para Gmail, GitHub ou uma API de sincronização, o cursor geralmente é crítico.

Reivindicação ou Arrendamento

Isso impede que dois trabalhadores peguem o mesmo trabalho.

claimed_by
claimed_at
claim_expires_at
run_id

Por exemplo, uma tarefa do Notion pode ser alterada de:

Status: Pendente

para:

Status: EmProgresso
ClaimedBy: hermes
ClaimedAt: 2026-06-19T01:00:00Z
ClaimExpiresAt: 2026-06-19T01:30:00Z
RunId: run_789

Esta é a diferença entre “espero que apenas um trabalhador pegue” e “o sistema tem um protocolo de reivindicação”.

Registro de Execução

Isso registra o que aconteceu durante uma execução.

run_id
poll_id
source_object_id
started_at
finished_at
status
items_checked
items_changed
decision_summary
error

O registro de execução deve viver no backend do assistente, não apenas no Notion ou em outra ferramenta externa. O Notion é bom para visibilidade humana. Não é ideal como seu único registro de execução.

Registro de Deduplicação

Isso impede notificações duplicadas ou ações repetidas.

dedupe_key
poll_id
source_object_id
condition_version
action_type
delivered_at

Por exemplo:

user_456:poll_123:notion_page_999:execute:v1

Se a mesma ação for tentada novamente, o sistema pode suprimi-la.

Método 1: Trabalhador de Polling Agendado

Este é o padrão mais simples e confiável.

Um agendador acorda em intervalos fixos e chama um trabalhador. O trabalhador lê a fonte, atualiza o estado e aciona uma ação do assistente, se necessário.

agendador
  -> trabalhador
  -> API da fonte
  -> banco de dados
  -> ação do assistente

Como Funciona

O agendador é responsável pelo tempo. Pode ser cron, um agendador em nuvem, um CronJob do Kubernetes ou um pequeno agendador interno.

A cada intervalo, ele inicia uma execução do trabalhador. O trabalhador carrega sua configuração, consulta a fonte de destino, compara o resultado com o estado armazenado e age, se necessário.

Para um assistente simples, isso geralmente é suficiente. Um único agendador e um processo de trabalhador leve podem lidar com dezenas de verificações diárias sem exigir filas, arrendamentos ou coordenação distribuída.

Modelo de Estado

O agendador armazena muito pouco. Geralmente, ele só sabe quando acionar um trabalho.

O banco de dados da aplicação armazena o estado importante:

definição de polling
agendamento
cursor ou instantâneo
último tempo de execução
contagem de falhas
status

O trabalhador deve ser sem estado. Ele pode conter dados temporários enquanto está em execução, mas a verdade durável pertence ao banco de dados.

Fluxo de Exemplo

A cada 10 minutos:
  acionar trabalhador de polling do Hermes

Trabalhador:
  carregar configuração de polling ativo
  consultar fonte
  comparar com estado anterior
  executar verificações determinísticas
  chamar LLM apenas se necessário
  atualizar estado
  emitir evento do assistente

Melhor Aplicação

Use trabalhadores de polling agendados para:

• Resumos diários.
• Verificações horárias.
• Automações internas pequenas.
• Tarefas simples de “observar isso”.
• Trabalhos de assistente de baixo a médio volume.

Fraquezas

O polling agendado é fácil de entender, mas pode se tornar frágil em escala. Se muitos polls forem executados ao mesmo tempo, você pode sobrecarregar seus trabalhadores ou atingir os limites de taxa do provedor. As tentativas também podem se tornar confusas se o agendador iniciar o trabalho diretamente.

Método 2: Trabalhadores de Polling Baseados em Fila

O polling baseado em fila geralmente é o padrão mais adequado para assistentes de IA em produção.

O agendador não executa o polling diretamente. Ele coloca um trabalho em uma fila. Os processos dos trabalhadores consomem trabalhos da fila.

agendador
  -> fila
  -> grupo de trabalhadores
  -> API da fonte
  -> repositório de estado
  -> ação do assistente

Como Funciona

Um agendador verifica os polls vencidos e enfileira trabalhos. Os trabalhadores puxam trabalhos quando têm capacidade.

Isso lhe dá contrapressão. Se o sistema estiver ocupado, os trabalhos aguardam na fila em vez de sobrecarregar a API da fonte ou o provedor de LLM.

Modelo de Estado

O banco de dados armazena o estado do polling:

poll_id
user_id
source_ref
condition_text
next_run_at
cursor
status
failure_count

A mensagem da fila deve permanecer pequena:

{
  "poll_id": "poll_123",
  "scheduled_for": "2026-06-19T01:10:00Z",
  "attempt": 1
}

O trabalhador carrega o estado completo do banco de dados quando inicia.

Fluxo de Exemplo

A cada minuto:
  agendador encontra polls onde next_run_at <= agora
  agendador enfileira trabalhos

Trabalhadores:
  puxam trabalhos da fila
  bloqueiam ou arrendam o polling
  consultam a fonte
  atualizam estado
  emitem ação do assistente se necessário
  definem next_run_at

Melhor Aplicação

Use polling baseado em fila para:

• Assistentes de IA multi-usuário.
• Muitos polls simultâneos.
• Integrações com limites de taxa.
• Trabalhos em segundo plano com capacidade de retry.
• Trabalhos que podem levar diferentes quantidades de tempo.
• Produtos SaaS onde a confiabilidade importa.

Fraquezas

As filas adicionam infraestrutura. Você precisa de tratamento de carta morta, idempotência, tempos de visibilidade e políticas de retry. Vale a pena para sistemas de produção, mas provavelmente é excessivo para um pequeno protótipo.

Método 3: Ferramenta Externa como Fila de Tarefas

Este é o padrão no exemplo de Notion mais Hermes.

A ferramenta externa não é apenas uma fonte de dados. Ela se torna a fila de tarefas voltada para o humano. O agente verifica periodicamente a ferramenta, reivindica uma tarefa, executa-a e atualiza o status da tarefa.

agendador
  -> trabalhador Hermes
  -> banco de dados Notion
  -> reivindicar uma tarefa
  -> executar tarefa
  -> atualizar status do Notion

Como Funciona

A cada 10 minutos, o Hermes consulta o banco de dados do Notion por uma tarefa no estado Pendente. Ele escolhe a próxima tarefa, geralmente por prioridade e tempo de criação. Em seguida, ele reivindica a tarefa definindo-a como EmProgresso.

Depois disso, o Hermes executa a tarefa. Se a execução for bem-sucedida, ele marca a tarefa como Concluída. Se a execução falhar, ele marca a tarefa como Falha ou a retorna para Pendente com uma contagem de retry.

Modelo de Estado

O Notion armazena o estado da tarefa voltado para o humano:

Título
Descrição
Status: Pendente | EmProgresso | Concluído | Falha
Prioridade
CriadoEm
ReivindicadoPor
ReivindicadoEm
ReivindicaExpiraEm
RunId
ContagemDeRetry
UltimoErro
ConcluídoEm

O backend do Hermes armazena o estado operacional de execução:

run_id
notion_page_id
started_at
finished_at
execution_status
tool_calls
LLM trace
error details
idempotency_key

Esta divisão é importante. O Notion é excelente para visibilidade e edição manual. O backend do Hermes é melhor para logs, retries, deduplicação e histórico de auditoria.

Fluxo de Exemplo

A cada 10 minutos:
  Hermes acorda

Hermes:
  consultar Notion por uma tarefa onde Status = Pendente
  ordenar por Prioridade, CriadoEm
  atualizar tarefa selecionada para EmProgresso
  definir ReivindicadoPor, ReivindicadoEm, ReivindicaExpiraEm, RunId
  executar a tarefa
  escrever log de execução
  definir tarefa como Concluído ou Falha

Melhor Aplicação

Use este padrão quando:

• Humanos já gerenciam trabalho no Notion, Jira, Linear, Trello ou outra ferramenta.
• Você quer que o assistente processe tarefas visíveis.
• O quadro de tarefas é a interface do usuário.
• Você precisa de um modelo de automação simples com humano no loop.

Fraquezas

As ferramentas externas raramente são filas perfeitas. As reivindicações atômicas podem ser limitadas. A consistência da consulta pode atrasar. Limites de taxa podem se aplicar. Se o agente puder ser executado em múltiplas instâncias, você precisa de uma estratégia de reivindicação ou arrendamento cuidadosa.

A recomendação prática é usar o Notion como a caixa de entrada de tarefas voltada para o humano, enquanto mantém todos os logs de execução, registros de retry, rastreamentos e chaves de idempotência no Hermes. O Notion dá visibilidade aos usuários; o Hermes mantém o sistema confiável. Para a mecânica do despachante e de concorrência que ficam por trás deste padrão no Hermes, consulte Kanban no Agente Hermes para Fluxos de Trabalho de LLM Auto-hospedados.

Método 4: Loop de Trabalhador de Longa Duração

Um loop de longa duração é a implementação mais simples.

while True:
    due_polls = db.find_due_polls()
    for poll in due_polls:
        run_poll(poll)
    sleep(30)

Este padrão combina agendamento e execução em um único serviço, o que o torna o ponto de partida mais simples possível para trabalho de agente em segundo plano.

Como Funciona

O processo do trabalhador é executado continuamente. A cada poucos segundos ou minutos, ele verifica o banco de dados por polls vencidos e os executa. É fácil de construir, fácil de raciocinar e rápido para iterar durante o desenvolvimento.

Modelo de Estado

O banco de dados ainda armazena estado durável:

configuração de polling
next_run_at
cursor
último resultado
contagem de falhas
status

A memória do processo deve conter apenas estado temporário:

lote atual
cache de curta duração
execução em voo

Nunca armazene progresso importante apenas na memória. Se o processo falhar, qualquer estado que não foi gravado no armazenamento durável desaparece, e a próxima execução não terá como saber onde as coisas pararam.

Melhor Aplicação

Use loops de longa duração para:

• Protótipos.
• Desenvolvimento local.
• Ferramentas internas.
• Sistemas de inquilino único.
• Agentes de baixo volume.

Fraquezas

Este padrão se torna arriscado com múltiplos réplicas. Sem arrendamentos, dois trabalhadores podem executar o mesmo polling. Ele também carece dos recursos operacionais de uma fila ou motor de fluxo de trabalho real.

Um loop de longa duração não está errado como ponto de partida, mas não é um agendador distribuído e não deve ser tratado como tal. Assim que você precisar de múltiplas réplicas ou garantias de confiabilidade mais fortes, você precisará migrar para um dos padrões mais estruturados acima.

Método 5: Webhook-First com Fallback de Polling

Se a fonte suporta webhooks, use-os. O polling deve frequentemente ser o backup, não o mecanismo principal. A mesma divisão aparece no design do protocolo de agente: notificações push A2A acordam um manipulador de cliente, que então faz polling em GetTask para obter o estado completo, conforme descrito em Streaming A2A e Tarefas Assíncronas para Fluxos de Trabalho de Agentes de Longa Duração.

sistema externo
  -> endpoint de webhook
  -> repositório de eventos
  -> ação do assistente

polling de reconciliação
  -> API da fonte
  -> comparar com repositório de eventos
  -> reparar eventos perdidos

Como Funciona

O sistema externo envia eventos para seu endpoint de webhook quando algo muda. Seu sistema armazena o evento e o processa assincronamente.

Um polling de reconciliação mais lento é executado a cada poucas horas ou uma vez por dia. Ele verifica se algum evento foi perdido.

Modelo de Estado

O repositório de eventos registra webhooks recebidos:

event_id
source_type
source_object_id
event_type
received_at
payload_hash
processed_at
signature_valid

O polling de reconciliação armazena:

last_reconciliation_at
last_seen_cursor
last_seen_version

A tabela de objetos da fonte armazena o último estado conhecido:

external_id
current_status
external_updated_at
last_processed_event_id

Melhor Aplicação

Use arquitetura webhook-first para:

• Eventos do GitHub.
• Eventos do Stripe.
• Eventos do Slack.
• Atualizações de CRM.
• Notificações de implantação.
• Sistemas de ticketing.

Fraquezas

Os webhooks exigem um endpoint público, validação de assinatura, proteção contra replay e deduplicação de eventos. Alguns provedores também enviam eventos incompletos, então você ainda pode precisar buscar o objeto completo.

Mesmo assim, se bons webhooks existirem, fazer polling a cada minuto geralmente é um desperdício.

Método 6: Polling de Trabalho em Segundo Lado do Provedor

Às vezes, a coisa sendo verificada é o trabalho de IA em si.

A aplicação inicia um trabalho de longa duração do provedor, armazena o ID do trabalho e verifica mais tarde se ele foi concluído.

app
  -> iniciar trabalho em segundo plano de IA
  -> armazenar ID do trabalho do provedor
  -> verificar status
  -> buscar resultado
  -> notificar usuário

Como Funciona

O assistente inicia um trabalho com o provedor. O provedor retorna um ID. Seu backend armazena esse ID e verifica seu status até que o trabalho tenha sucesso, falhe, expire ou atinja o tempo limite.

Modelo de Estado

Seu backend armazena:

assistant_task_id
provider_job_id
user_id
status
created_at
last_checked_at
expires_at
result_ref

O provedor armazena o estado temporário do trabalho e a saída.

Se a saída for importante, copie-a para seu próprio armazenamento durável assim que o trabalho for concluído. O armazenamento de resultados do lado do provedor tem janelas de retenção curtas e não é um substituto para um arquivo adequado em seu próprio sistema.

Melhor Aplicação

Use polling de trabalho em segundo lado do provedor para:

• Tarefas de pesquisa de IA de longa duração.
• Processamento de documentos grandes.
• Análise de base de código.
• Geração de relatórios.
• Trabalhos de extração de dados.
• Tarefas que excedem os tempos limite normais de solicitações HTTP.

Fraquezas

Este padrão resolve um problema: esperar por um trabalho de provedor longo. Ele não substitui seu motor de fluxo de trabalho, agendador, fila ou repositório de estado de negócios.

Método 7: Motor de Fluxo de Trabalho Durável

Um motor de fluxo de trabalho durável gerencia execução de longa duração, temporizadores, retries e recuperação. O Temporal é a escolha mais comum para backends de assistentes baseados em Go e Python; para um guia de implementação completo, consulte Implementando Aplicações de Fluxo de Trabalho com Temporal em Go.

Em vez de conectar manualmente cada espera e retry, você modela o processo como um fluxo de trabalho.

motor de fluxo de trabalho
  -> atividade: verificar fonte
  -> temporizador: esperar
  -> atividade: avaliar resultado
  -> atividade: notificar usuário

Como Funciona

O fluxo de trabalho inicia uma vez e então controla sua própria espera. Ele pode dormir por minutos, dias ou semanas. Se o processo do trabalhador falhar, o motor de fluxo de trabalho pode retomar a partir do estado gravado.

Modelo de Estado

O motor de fluxo de trabalho armazena:

workflow_id
execution history
timer state
activity attempts
retry policy
current workflow state

Seu banco de dados da aplicação armazena:

user-facing poll definition
authorization references
business records
notification records

O motor de fluxo de trabalho possui o estado do processo — histórico de execução, temporizadores, retries e tentativas de atividade. Seu banco de dados possui o estado de negócios — configurações do usuário, registros de autorização, notificações e logs de auditoria. Manter esses separados impede que cada camada se torne um híbrido confuso de ambos.

Melhor Aplicação

Use fluxos de trabalho duráveis para:

• Processos de negócios multi-etapa.
• Automações de longa duração.
• Fluxos de aprovação humana.
• Retries confiáveis.
• Trabalho em segundo plano auditável.
• Processos que devem retomar após falha.

Fraquezas

Os motores de fluxo de trabalho adicionam conceitos e infraestrutura. Eles são excelentes quando o processo é importante, mas pesados para verificações horárias simples.

Método 8: Runtime de Agente Persistente

Algumas estruturas de agente podem persistir o estado do agente, fazer checkpoint da execução e retomar mais tarde.

Isso é útil quando o agente em si tem um processo de raciocínio multi-etapa.

agendador ou fluxo de trabalho
  -> runtime do agente
  -> carregar checkpoint
  -> chamar ferramentas
  -> salvar checkpoint
  -> retomar mais tarde

Como Funciona

Um agendador externo ou fluxo de trabalho inicia o agente. O runtime do agente carrega o estado anterior, executa o próximo passo, chama ferramentas se necessário e grava um checkpoint.

O runtime do agente não deve ser seu único agendador. É melhor tratado como a camada de raciocínio dentro de uma arquitetura de backend maior.

Modelo de Estado

O armazenamento de checkpoint do agente contém:

current node
messages
tool outputs
intermediate reasoning state
pending action

A memória de longo prazo contém:

stable user preferences
facts
project context
source references

O estado operacional ainda pertence a outro lugar:

poll schedule
cursor
status
retry count
dedupe records

Uma regra útil: memória não é um cursor, e um checkpoint não é uma fila. A memória do agente armazena o que o modelo sabe; o estado operacional rastreia onde o processo está e o que ele fez. Conflitar os dois leva a bugs sutis que só aparecem sob concorrência ou após uma reinicialização. O espaço de design completo para memória de trabalho, estado durável e camadas de recuperação é coberto em Sistemas de Memória em Assistentes de IA.

Melhor Aplicação

Use runtime de agente persistente para:

• Pesquisa multi-etapa.
• Agentes que pausam e retomam.
• Trabalho com humano no loop.
• Raciocínio pesado em ferramentas.
• Tarefas onde o contexto se acumula ao longo do tempo.

Fraquezas

A persistência do agente não é a mesma que confiabilidade operacional. Você ainda precisa de agendamento, bloqueio, retries, limites de taxa e logs de auditoria.

Método 9: Sincronização de Banco de Dados Mais Avaliação de Mudança

Neste padrão, o polling é usado para sincronizar dados externos para seu próprio banco de dados. O assistente então reage às mudanças locais no banco de dados em vez de consultar APIs externas diretamente em cada ciclo de avaliação.

sync poller
  -> external API
  -> local database
  -> change evaluator
  -> assistant action

Isso separa a sincronização de dados da inteligência do assistente. O trabalhador de sincronização é responsável por manter os registros locais atualizados; o avaliador é responsável por decidir o que fazer sobre as mudanças. Cada camada pode ser testada, monitorada e escalada independentemente.

Como Funciona

O trabalhador de sincronização periodicamente busca mudanças externas e grava registros normalizados em seu banco de dados. Um segundo trabalhador ou fluxo de mudanças detecta linhas atualizadas e decide se o assistente deve agir.

Modelo de Estado

A tabela de sincronização armazena:

external_id
source_type
raw_payload
normalized_fields
external_updated_at
synced_at
version
content_hash

O estado de sincronização armazena:

source_cursor
last_sync_at
rate_limit_status
failure_count

A tabela de avaliação do assistente armazena:

object_id
evaluation_status
last_evaluated_hash
decision
notification_id

Melhor Aplicação

Use este padrão para:

• Sincronização de CRM.
• Sistemas de ticketing.
• Documentos contábeis.
• Inventário de produtos.
• Revisão de conformidade.
• Indexação de busca.
• Painéis internos.

Fraquezas

Sincronizar tudo pode ser caro e desnecessário. Também pode criar obrigações de privacidade e retenção. Use este padrão quando dados locais tenham valor além de uma única ação do assistente.

Método 10: Polling Adaptativo

O polling adaptativo muda a frequência com base no estado, urgência ou atividade recente.

active object: poll every 1 minute
waiting object: poll every 1 hour
stale object: poll once per day
completed object: stop polling

Como Funciona

Após cada execução, o trabalhador decide quando a próxima execução deve acontecer.

Se o objeto mudou recentemente, faça polling mais cedo. Se nada mudou por um longo tempo, diminua a velocidade. Se a tarefa estiver completa, pare.

Modelo de Estado

O estado do polling inclui:

current_interval
minimum_interval
maximum_interval
backoff_policy
last_activity_at
priority
stop_condition

O instantâneo da fonte inclui:

status
updated_at
activity_level
expected_next_change

Melhor Aplicação

Use polling adaptativo para:

• Status de implantação.
• Rastreamento de entrega.
• Disponibilidade de horário do calendário.
• Monitoramento de preços.
• Trabalhos de build.
• Tarefas de provedor de longa duração.
• Qualquer fonte com atualizações em rajada.

Fraquezas

O polling adaptativo pode ser mais difícil de raciocinar. Se uma tarefa deve ser executada em um horário estrito, mantenha-o estrito. Não torne tarefas de conformidade inteligentes.

Método 11: Polling Semântico com Avaliador LLM

O polling semântico é usado quando a condição é vaga.

Código pode responder:

Is status equal to Complete?
Is price below 100?
Is there a new message?

Um LLM pode ajudar a responder:

Does this email sound urgent?
Is this customer likely unhappy?
Is this research paper relevant?
Does this change require my attention?

Como Funciona

O trabalhador primeiro aplica filtros determinísticos baratos. Apenas itens candidatos vão para o LLM.

new item?
matches source filters?
not already processed?
not obviously irrelevant?

Então o LLM avalia o conjunto candidato menor e retorna saída estruturada.

{
  "should_notify": true,
  "urgency": "high",
  "reason": "The customer reports a production outage."
}

Modelo de Estado

A definição de polling armazena:

semantic_condition
examples
negative_examples
user_preference_summary
model_config

O log de avaliação armazena:

input_reference
model
prompt_version
structured_output
confidence
cost
latency

O estado do polling armazena:

last_seen_ids
last_evaluated_hashes
last_decision
last_decision_reason

Melhor Aplicação

Use polling semântico para:

• Detecção de e-mails importantes.
• Monitoramento de sentimento do cliente.
• Alertas de pesquisa.
• Detecção de oportunidades de vendas.
• Triagem de segurança.
• Breves executivos.

Fraquezas

As chamadas de LLM custam dinheiro e adicionam latência. Elas também podem ser inconsistentes se os prompts e esquemas forem soltos. Use filtros determinísticos primeiro. Pergunte ao modelo apenas quando o julgamento for realmente necessário.

Tabela de Decisão: Escolhendo um Método de Agente de Polling

Arquitetura Padrão Recomendada

Para a maioria dos assistentes de IA em produção, comece com isso:

polls table
  -> scheduler
  -> queue
  -> stateless workers
  -> deterministic filters
  -> optional LLM evaluator
  -> notification or assistant action

Um esquema mínimo:

CREATE TABLE polls (
    id TEXT PRIMARY KEY,
    user_id TEXT NOT NULL,
    source_type TEXT NOT NULL,
    source_ref TEXT NOT NULL,
    condition_text TEXT NOT NULL,
    schedule_type TEXT NOT NULL,
    interval_seconds INTEGER,
    timezone TEXT,
    next_run_at TIMESTAMP NOT NULL,
    last_run_at TIMESTAMP,
    cursor_value TEXT,
    last_hash TEXT,
    status TEXT NOT NULL,
    failure_count INTEGER NOT NULL DEFAULT 0,
    last_error TEXT,
    created_at TIMESTAMP NOT NULL,
    updated_at TIMESTAMP NOT NULL
);

CREATE TABLE poll_runs (
    id TEXT PRIMARY KEY,
    poll_id TEXT NOT NULL,
    started_at TIMESTAMP NOT NULL,
    finished_at TIMESTAMP,
    status TEXT NOT NULL,
    items_checked INTEGER,
    items_matched INTEGER,
    decision_summary TEXT,
    error TEXT
);

CREATE TABLE notifications (
    id TEXT PRIMARY KEY,
    poll_id TEXT NOT NULL,
    user_id TEXT NOT NULL,
    dedupe_key TEXT NOT NULL,
    title TEXT NOT NULL,
    body TEXT NOT NULL,
    delivered_at TIMESTAMP,
    UNIQUE (dedupe_key)
);

Isso lhe dá uma separação limpa:

scheduler owns time
queue owns buffering
worker owns execution
database owns state
LLM owns semantic judgment
assistant owns user interaction

Essa separação é o coração de um agente de polling confiável.

Exemplo: Agente Hermes Processando Tarefas do Notion

Agora vamos aplicar a arquitetura a um caso concreto.

Assuma que um banco de dados do Notion contém tarefas. O Hermes deve rodar a cada 10 minutos, pegar uma tarefa no estado Pendente, defini-la como EmProgresso, executá-la e então marcá-la como Concluída.

Isso é melhor descrito como:

external tool as task queue
+
scheduled polling worker
+
claim or lease based execution

Para uma versão de produção, torna-se:

queue-based polling with Notion as the human-facing task inbox

Propriedades da Tarefa do Notion

O banco de dados do Notion deve conter campos como:

Name
Status: Todo | InProgress | Complete | Failed
Priority
CreatedAt
ClaimedBy
ClaimedAt
ClaimExpiresAt
RunId
RetryCount
LastError
CompletedAt

Os campos importantes são ClaimedAt, ClaimExpiresAt e RunId. Eles tornam a reivindicação da tarefa visível e recuperável.

Estado de Execução do Hermes

O Hermes também deve manter seu próprio registro de execução:

run_id
notion_page_id
started_at
finished_at
status
input_snapshot
tool_calls
result_summary
error
idempotency_key

Isso o protege se o Notion for editado manualmente, se uma chamada de API falhar ou se você precisar auditar o que o Hermes realmente fez.

Fluxo de Execução

Every 10 minutes:
  Hermes scheduler creates a run

Hermes worker:
  finds one Notion task where Status = Todo
  sorts by Priority and CreatedAt
  claims the task by setting Status = InProgress
  writes ClaimedBy, ClaimedAt, ClaimExpiresAt, and RunId
  executes the task
  writes execution logs to Hermes backend
  sets Notion Status = Complete on success
  sets Notion Status = Failed on failure

Se o Hermes falhar após reivindicar uma tarefa, o arrendamento pode expirar:

Status = InProgress
ClaimExpiresAt < now

Uma execução futura pode então recuperar a tarefa ou marcá-la como falha.

Tratamento de Falha

Com sucesso:

Status = Complete
CompletedAt = now
LastError = empty

Em falha recuperável:

Status = Todo
RetryCount = RetryCount + 1
LastError = short error message

Em falha não recuperável:

Status = Failed
LastError = clear explanation

Para segurança, o Hermes também deve usar uma chave de idempotência:

notion_page_id + task_version + action_type

Isso impede que a mesma tarefa seja executada duas vezes se um retry acontecer no momento errado.

Por Que Isso Não é Apenas Polling

A parte do polling é apenas o mecanismo de despertar. A verdadeira arquitetura é reivindicação de tarefa e execução confiável.

Uma implementação ingênua diz:

Every 10 minutes, find a Todo task and do it.

Uma implementação confiável diz:

Every 10 minutes, claim exactly one eligible task, record the run, execute idempotently, and move the task to a terminal state.

Essa é a diferença entre uma demonstração e um agente em que você pode confiar.

Erros Comuns de Agentes de Polling

Erro 1: Sem Protocolo de Reivindicação

Se dois trabalhadores podem ver a mesma tarefa, eles podem executá-la ambos.

Use:

ClaimedBy
ClaimedAt
ClaimExpiresAt
RunId

Mesmo que você atualmente execute um trabalhador, projete como se um segundo trabalhador pudesse aparecer mais tarde.

Erro 2: Sem Chave de Deduplicação

Toda ação externa deve ter uma chave de deduplicação.

user_id + poll_id + source_object_id + action_type + condition_version

Isso impede notificações repetidas, e-mails repetidos, execução de tarefas repetidas e chamadas de ferramentas repetidas. Os princípios mais amplos por trás do escopo, armazenamento e teste dessas chaves se aplicam igualmente aqui — consulte Idempotência em Sistemas Distribuídos que Realmente Funciona.

Erro 3: Chamando o LLM Muito Cedo

Não peça ao modelo para fazer filtragem de banco de dados.

Ruim:

Send all tasks to the LLM and ask which one is Todo.

Melhor:

Use the Notion API filter to fetch Todo tasks.
Then use the LLM only if task interpretation is needed.

Erro 4: Tratando o Notion como o Único Backend

O Notion é uma boa interface humana. Não é um backend de execução completo.

Mantenha logs de execução, retries, rastreamentos e registros de idempotência no Hermes.

Erro 5: Polling Infinito

Todo polling deve ter uma condição de parada.

Exemplos:

stop after success
stop after date
stop after max retries
stop when user disables it
stop after repeated authorization failure

Um agente de polling sem condição de parada é um vazamento de custo silencioso.

Erro 6: Sem Observabilidade

Você deve ser capaz de responder:

What did the agent run?
Why did it run?
What did it read?
What did it change?
Why did it fail?
Did it notify the user?
Did it run twice?

Se você não puder responder a essas perguntas, o sistema não está pronto para trabalho importante.

Lista de Verificação de Observabilidade

Rastreie métricas como:

polls_due
polls_started
polls_succeeded
polls_failed
tasks_claimed
tasks_completed
tasks_failed
claim_expired_count
duplicate_suppressed_count
llm_calls
llm_cost
rate_limit_count
average_run_duration

Campos de log como:

poll_id
run_id
source_type
source_object_id
claim_id
cursor_before
cursor_after
decision
dedupe_key
error

Construa uma visão administrativa para:

active polls
stuck InProgress tasks
recent failures
high retry tasks
dead letter jobs
expensive LLM evaluations
disabled integrations

Os agentes de polling rodam em segundo plano, onde falhas são silenciosas e problemas podem se acumular antes que alguém perceba. Sistemas em segundo plano precisam de visibilidade construída desde o início, não adicionada como um pensamento tardio quando algo dá errado. Para a pilha completa de observabilidade para sistemas de IA e LLM — métricas, rastreamentos, logs estruturados e SLOs — consulte Observabilidade para Sistemas de LLM: Métricas, Rastreamentos, Logs e Testes em Produção.

Recomendação Final

Os padrões de polling lidam com a camada de agendamento proativo sob um sistema multi-agente. Uma vez que você tem múltiplos agentes que precisam coordenar entre si — não apenas fazer polling independentemente — a próxima decisão de design é como eles coordenam: hub-and-spoke, pipeline, fan-out ou swarm. Padrões de Orquestração Multi-Agente cobre essas topologias de coordenação com modos de falha e um framework de decisão.

Para um assistente de IA sério, comece com trabalhadores de polling baseados em fila e um repositório de estado durável. Adicione webhooks onde os provedores os suportam. Use polling adaptativo quando limites de taxa importarem. Use um motor de fluxo de trabalho durável quando o processo for de longa duração e multi-etapa. Use runtime de agente persistente quando o agente precisar raciocinar ao longo do tempo.

Para o exemplo de Hermes e Notion, a arquitetura certa é:

Notion as the human-facing task inbox
Hermes scheduler every 10 minutes
Hermes worker with claim or lease logic
Hermes backend for execution logs and idempotency
Notion status updates for visibility

O intervalo de polling não é a parte difícil. A parte difícil é garantir que o agente reivindique uma tarefa, a execute uma vez, registre o que aconteceu e deixe o sistema em um estado que humanos possam entender.

Isso é o que transforma um script de polling em um assistente de IA confiável — não o intervalo, não o modelo, mas a disciplina em reivindicar trabalho, registrá-lo e deixar o sistema em um estado que humanos e execuções futuras possam entender.