Atualizado em Aug 28, 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 mais uma nota de lembrete. O passo retorna imediatamente com um monitorId; quando a vigia corresponder, o AutoTalk publica uma mensagem de evento de monitor na conversa, e o agente acorda pelo pipeline normal de mensagens com todo o histórico da conversa. A nota que você escreveu é reproduzida nesse evento — ela é a sua instrução para o seu eu do futuro.

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	Menos de um segundo para trabalhos de transcrição/conversão (os motores deles acionam o sweeper diretamente); o próximo minuto do sweeper (até ~1 min) para outros documentos	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)

Regra de bolso: nunca use agent_tool para algo que o AutoTalk já controla. Um trabalho de transcrição, uma conversão de mídia, qualquer documento da empresa — dynadata_doc acorda para esses em menos de um segundo. agent_tool é uma consulta periódica; ele existe para o mundo fora do AutoTalk, que você vigia embrulhando a leitura (uma requisição HTTP, por exemplo) em uma ferramenta normal do agente. Assim as credenciais ficam na configuração dos passos da ferramenta, nunca no prompt do modelo.

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.: step(0).jobId). Só tipos publicados legíveis pelo tenant e tipos personalizados ct: podem ser vigiados
condition	Uma string CEL simples (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

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

Escrevendo a condição

Use verificações positivas. Um campo ausente do documento vigiado é lido como null, então uma comparação negativa como doc.outputs.txt != '' é verdadeira enquanto o campo ainda não existe e dispara imediatamente. Escreva doc.status == 'done', não "qualquer coisa exceto pendente".

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).

Como a condição é uma string simples, você não consegue interpolar um limite nela. 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 completo; 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 step(N).monitorId, não por step(N).status — status é reservado para códigos de status HTTP.