Iris — agentes autônomos que rodam 24/7

Iris é a camada proativa da plataforma. Em vez de o usuário puxar o agente a cada pergunta, o Iris roda segundo um schedule, observa o estado do seu negócio e decide sozinho o que fazer — alertar, notificar, registrar, agir.

A diferença pro nosso engine de Fluxos é fundamental:

• Fluxos são passo-a-passo determinístico — você escreve a sequência exata de ações.
• Iris é objetivo narrativo — você descreve a missão (ex: "monitore vendas e avise se cair >20%") e o LLM decide as ações dentro das tools disponíveis.

Quando usar Iris

Bom encaixe:

• Monitoramento de KPI — "avise quando algo fugir da média".
• Resumo periódico — "toda manhã às 8h manda resumo do dia anterior no Slack".
• Watcher de anomalias — "se o gasto de tokens disparar, me avisa".
• Follow-up inteligente — "olhe leads sem resposta há 3 dias e envie mensagem de retomada só pros quentes".

Mau encaixe:

• Ação com cadência exata e passos rígidos (ex: "todo dia 15, envia cobrança X pra cliente Y") — use Fluxos.
• Resposta reativa a pergunta do usuário — use Chat / agente comum.
• Trigger por evento externo (webhook, mensagem recebida) — use Workflows.

Como o Iris é composto

Cada Iris reusa um agente base que você já criou — herda dele:

• System prompt
• Modelo LLM + temperatura
• Tools disponíveis (incluindo MCP bindings)

O que o Iris adiciona em cima:

• Objetivo narrativo — a "missão" da execução
• Schedule cron — quando disparar
• Memória persistente (state) — JSON que o agente atualiza a cada run e lê na próxima (ex: "last_daily_volume: 142", "last_anomaly_at: 2026-04-20T15:00")

Templates prontos

Ao criar um Iris, você pode começar de um template:

Cada template vem com nome, objetivo e schedule pré-preenchidos — você pode editar antes de salvar.

Passo a passo: criar seu primeiro Iris

1. Vá em Iris (autônomos) na sidebar.
2. Clique Criar Iris.
3. Opcional: escolha um template no dropdown. Os campos se preenchem.
4. Agente base: escolha qual agente empresta prompt + modelo + tools.
5. Nome: algo identificável no dashboard (ex: "Monitor Vendas Filial SP").
6. Objetivo: descreva a missão em português. Pode ser longo — o LLM lê como briefing.
7. Frequência: escolha um preset ou configure cron custom (formato padrão Unix, 5 campos).
8. Clique Criar.

O Iris entra em fila e roda na próxima janela de 5 minutos.

Escrever um objetivo que funciona

O objetivo é a parte mais importante. Pense nele como um briefing pra uma pessoa nova no time que vai executar a rotina. Boas práticas:

1. Diga o que observar primeiro. "Consulte quantos leads novos chegaram hoje" é melhor que "monitore leads".
2. Diga quando agir e quando calar. "Se o número estiver abaixo de 5, envie alerta no Slack. Se estiver acima, não faça nada — silêncio é valor."
3. Peça updates de state. "Ao final, registre em state o número observado com chave last_daily_leads para a próxima execução comparar."
4. Evite instruções ambíguas. "Avise se estiver ruim" é ruim. "Avise se cair mais de 20% em relação à média 7d" é bom.

Exemplo de objetivo bem escrito:

Sua missão é monitorar handoffs para atendimento humano:

1. Consulte quantos handoffs ocorreram hoje (até agora) via Postgres MCP.
2. Compare com a média dos últimos 7 dias úteis (guarde em state["avg_handoffs"]).
3. Se o dia atual estiver >50% acima da média, mande alerta no Slack do
   canal #atendimento-urgente com número observado, média e %.
4. Se estiver dentro do esperado, não envie nada.
5. Atualize state["last_daily_handoffs"] com o número de hoje ao final.

Memória persistente (state)

O state é um JSON que o Iris mantém entre execuções. Pense nele como o "caderno" do agente.

No prompt inicial, o agente vê:

# Sua memória persistente (state atual)
{
  "avg_handoffs": 12.5,
  "last_daily_handoffs": 14,
  "last_alert_at": "2026-04-21T18:00:00Z"
}

Pra atualizar, o LLM chama a tool especial update_iris_state com um patch JSON. Não há esquema forçado — use as chaves que fizerem sentido pro objetivo. Evite guardar dados sensíveis (o state fica auditável por qualquer owner/admin).

Controlar um Iris

Na lista do dashboard, cada card tem:

• Link de execuções — abre a trilha de runs (status, summary, actions_taken, state before/after, tokens).
• Executar agora — força next_run_at = now. O próximo tick do cron (até 5 min) pega.
• Switch — pausa/ativa. Pausado, o Iris não gasta tokens nem dispara ações.
• Deletar — hard delete. A trilha de runs também some.

Custos

Cada execução do Iris consome tokens do seu plano igual uma conversa normal. O agente base determina o custo por token. Cada run registra:

• Tokens consumidos (input + output)
• Custo estimado em USD

Veja o gasto agregado em Analytics ou no histórico de runs de cada Iris.

Limites

• Timeout por run: 50 segundos. Se o objetivo exigir mais, divida em Irises menores ou simplifique.
• Max 3 Irises por invocação de cron — evita sobrecarga de janela. Se você tiver 10 ativos com mesmo horário, vão rodar ao longo dos ticks (5 min cada).
• Schedule mínimo: 5 minutos. Não há como fazer Iris "a cada minuto".
• Sem loop de control: o LLM faz UMA rodada por run. Se quiser encadeamento, crie dois Irises.

Auditoria

Toda execução — sucesso, erro ou skip — gera evento em /dashboard/auditoria categoria Agentes com:

• iris.run_success / iris.run_failed
• iris.created / iris.deleted / iris.enabled / iris.disabled

Útil pra compliance e pra debugar regressão de comportamento.

Próximos passos

Depois de criar seu primeiro Iris, acompanhe a tela de execuções pelos primeiros dias. Ajuste o objetivo baseado no que você vê na coluna Narrativa — ela mostra como o LLM interpretou a missão. Se estiver enviesado ou exagerado em algum comportamento, refine o objetivo.

Em caso de erro recorrente, o card mostra Último erro logo abaixo do título — use isso pra diagnosticar antes de abrir o Sentry.