Atualizado em Oct 9, 2026

Criar Monitor

Tipo de ação: actions/monitors/create.

Use esta ação quando um agente (ou workflow) precisar ser acordado mais tarde — quando um documento mudar, em um horário definido, ou quando algo fora do AutoTalk chegar a um estado que interessa.

Um monitor é uma vigia registrada com um lembrete. A etapa retorna imediatamente com monitorId; quando uma verificação corresponde, o AutoTalk publica um evento de monitor na conversa e o agente pode continuar pelo fluxo normal de mensagens. O histórico é limitado pelo orçamento de contexto e pode ser reduzido. O evento repete sua nota como lembrete para a próxima execução.

Ideal para

• Entregar o resultado de um trabalho longo (uma transcrição, uma conversão de mídia) na mesma conversa quando ele terminar — sem ficar consultando
• Autolembretes do tipo "me lembre em 30 minutos"
• Vigiar algo fora do AutoTalk — o status de um ticket, um preço, um trabalho externo — reexecutando uma das ferramentas somente-leitura do próprio agente em um cronograma

Os três tipos de vigia

Tipo de vigia	Vigia	Latência do despertar	Precisa de
dynadata_doc	Um documento da sua empresa (por exemplo uma linha de transcription_jobs, ou um documento de tipo personalizado ct:) até uma condição CEL sobre ele valer	Verificações aceleradas após transcrição/transcode; varreduras periódicas para outras alterações. Podem ficar na fila, falhar ou ser repetidas; a latência não é garantida	itemType + itemId + condition
time	O relógio	O próximo minuto do sweeper após fireAt	fireAt ou delayMinutes
agent_tool	O resultado de uma das ferramentas do próprio agente, reexecutada em um cronograma	A primeira consulta cuja condição valer — as consultas rodam a cada intervalMinutes (mínimo 5)	toolName + condition (+ toolArgs, intervalMinutes)

Use vigias de documento para dados do AutoTalk. Um job de transcrição, transcode ou documento da empresa pode usar dynadata_doc; a conclusão pode solicitar uma verificação acelerada. agent_tool consulta periodicamente e serve para dados externos lidos por uma ferramenta do agente. Mantenha credenciais na configuração das etapas, não no prompt. Todas as verificações podem ficar na fila, falhar ou ser repetidas.

Campos principais

Campo	O que faz
watchType	CEL que resolve para dynadata_doc, time ou agent_tool
itemType / itemId	Só dynadata_doc: o tipo e o _id do documento vigiado (ex.: workflow.step(0).jobId). Só tipos publicados legíveis pelo tenant e tipos personalizados ct: podem ser vigiados
condition	Um descritor CEL nativo {expr: "..."} (não avaliada na criação — só verificada sintaticamente) que o sweeper avalia depois. Para dynadata_doc ela roda sobre doc (o documento vigiado); para agent_tool veja a arena abaixo
fireAt / delayMinutes	Só time: quando disparar — um datetime ISO, ou minutos a partir de agora
agentId / toolName / toolArgs	Só agent_tool: qual ferramenta reexecutar. agentId assume por padrão o agente que roda o passo; toolName precisa ser único naquele agente (um nome duplicado é recusado em vez de adivinhado); toolArgs é um objeto de argumentos escalares verificado contra os parâmetros declarados da ferramenta na criação
intervalMinutes	Só agent_tool: com que frequência consultar. Limitado a 5–1440 e com variação aleatória — nunca mais rápido que 5 minutos
note	Seu lembrete, reproduzido literalmente no despertar. Escreva o que o agente deve fazer quando a vigia disparar
conversationId	Qual conversa acordar. Assume por padrão a conversa em que a execução está — uma execução de workflow não tem conversa, então passos de workflow precisam defini-lo
ttlMinutes	Por quanto tempo a vigia fica armada. Padrão 1440 (24 h), máximo 10080 (7 dias). Depois disso o monitor expira sem disparar

O que passos seguintes podem usar

• workflow.step(N).monitorId — o id do monitor armado (consulte-o pelo tipo de dados somente-leitura monitors)
• workflow.step(N).monitorState — armed no momento da criação
• workflow.step(N).expiresAtIso — quando a vigia morre sem disparar

Escrevendo a condição

Um campo ausente é um erro de avaliação. Uma condição sem proteção, como doc.outputs.txt != '', falha enquanto outputs ou txt estiver ausente e conta para o limite de falhas de avaliação. Três falhas consecutivas encerram o monitor com error e notificam a sua equipe. Para continuar aguardando dados opcionais, use uma proteção de presença, como has(doc.status) && doc.status == 'ready', ou leia um valor padrão seguro: maps.get(doc, 'outputs.txt', '') != ''. Uma condição que avalia com sucesso como false mantém o monitor armado.

Para dynadata_doc, a condição enxerga doc — o documento vigiado.

Para agent_tool, a condição enxerga a saída declarada da própria ferramenta:

Variável	O que é
output	O resultado renderizado do output.main da ferramenta
outputText	O mesmo, sempre como string
data	A saída da ferramenta interpretada como JSON, quando é um objeto ou array JSON — caso contrário null. Interpretada a partir da saída completa antes do corte de exibição, então data continua utilizável mesmo quando outputText é truncado
steps	Por passo, {ok, status, error} — ok é verdadeiro para um passo concluído cujo status HTTP, se houver, é 2xx
now	O momento da avaliação

Exemplo: data.atingiu == true, ou steps[0].status == 200. Os payloads por passo deliberadamente não são expostos — a condição só enxerga o que o output.main da própria ferramenta projeta, e a ferramenta vigiada precisa declarar um output.main (uma ferramenta sem ele é recusada: sua condição nunca poderia se tornar verdadeira).

O descritor da condição é armazenado sem avaliação na criação; a arena de execução inclui os bindings declarados. Coloque a parte variável em toolArgs e faça a ferramenta calcular o veredito — por exemplo um parâmetro limite que a ferramenta compara, de forma que a condição seja apenas data.atingiu == true.

O que uma ferramenta vigiada pode fazer

Uma vigia agent_tool reexecuta a ferramenta sem modelo — sem conversa, sem supervisão, por até sete dias. Então a ferramenta só pode ler:

• Todo passo precisa ser uma ação somente-leitura (requisição HTTP, buscar/pesquisar/contar dados da empresa, resolver variáveis). Qualquer coisa que grave dados, envie mensagens, gaste dinheiro ou emita credenciais é recusada — na criação e verificada de novo a cada consulta.
• No máximo 5 passos, e a ferramenta inteira precisa terminar em 25 segundos por consulta — uma ferramenta que funciona bem como ferramenta de LLM (um passo HTTP sozinho permite 120 s) pode estourar isso como vigia; três estouros consecutivos encerram a vigia.
• Um passo que responde com HTTP 4xx/5xx conta como dado concluído (steps[i].ok falso, status preenchido) e a vigia continua consultando — então uma condição pode vigiar a recuperação. Uma consulta só conta para as falhas quando um passo não consegue rodar de jeito nenhum (falha de DNS, conexão recusada, timeout) e nenhum passo da cadeia foi concluído — um passo concluído faz a consulta estacionar como "não atendida". Para detectar um passo posterior falhando persistentemente, coloque steps[i].ok na sua condição.

Editar a ferramenta vigiada encerra a vigia

A vigia registra uma impressão digital da superfície executável da ferramenta como ela era quando foi armada — nome, parâmetros, passos e expressão de saída. Se qualquer um desses mudar, ou a ferramenta for removida ou duplicada por nome, o monitor para imediatamente com uma notificação para a sua equipe — ele não continua rodando silenciosamente uma versão antiga, e não adivinha entre duas ferramentas com o mesmo nome. Edições cosméticas (a descrição, ocultar a ferramenta) não encerram a vigia. Rearme depois de terminar edições de comportamento.

Limites

• 10 monitores armados por conversa, 50 por conta, e 10 vigias agent_tool armadas por conta (cada uma é uma consulta recorrente). Um monitor de que você não precisa mais pode ser cancelado com Cancelar Monitor — cancelar libera a vaga imediatamente
• 20 disparos por conversa por dia — cada disparo é uma execução de agente cobrável; um monitor que atinge o teto entra no caminho de erro em vez de retomar no dia seguinte
• Uma execução que foi ela mesma acordada por um monitor pode armar um monitor a mais (profundidade 1); encadear além disso é recusado, então loops vigia → despertar → vigia → despertar não conseguem fugir do controle
• Três falhas de avaliação consecutivas mudam o monitor para error e notificam a sua equipe

Dicas

• Encerre a execução normalmente depois de armar — envie ao usuário uma resposta provisória ("Te aviso assim que estiver pronto"). O despertar continua a conversa depois com o histórico mantido dentro do orçamento de contexto; o monitor é como você para de consultar, não mais uma coisa para esperar.
• O despertar chega como uma mensagem de evento de monitor carregando a sua nota e um retrato do que correspondeu. Adicione um prompt de sistema dizendo ao agente como tratar esses eventos — veja Despertares assíncronos.
• Leia o resultado da criação por workflow.step(N).monitorId, não por workflow.step(N).status — status é reservado para códigos de status HTTP.