> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leme.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Triggers

> Execute agents automaticamente por horário ou por webhook

## Visão geral

Triggers iniciam um agent automaticamente. Use-os para rotinas recorrentes, como um briefing diário, ou para fluxos baseados em eventos, como qualificar um novo lead quando um formulário é enviado.

Triggers não substituem canais nem integrações. Canais são onde pessoas conversam com um agent. Integrações e conexões são como o agent acessa ferramentas externas. Um trigger só decide quando uma execução começa.

## Tipos de trigger

**Schedule** executa um agent em um horário configurado. Use para rotinas diárias, semanais ou baseadas em cron. Confira sempre o fuso horário antes de ativar.

**Webhook** executa um agent quando um sistema externo envia um evento autenticado. Use para formulários, alertas, eventos de ciclo de vida ou outras notificações externas.

## Antes de começar

Você precisa ter role `Owner` ou `Admin` no workspace para criar e gerenciar triggers.

Confirme que o agent está ativo e tem as conexões ou ferramentas necessárias. Runs iniciados por trigger seguem as mesmas permissões, regras de aprovação e acesso a tools que runs manuais.

## Criar um trigger schedule

1. Abra o agent no dashboard da Leme.
2. Vá para a aba **Triggers**.
3. Selecione **Novo trigger**.
4. Escolha **Schedule**.
5. Adicione um nome e uma instrução claros.
6. Escolha um horário diário, semanal ou cron.
7. Confirme o fuso horário.
8. Escolha o comportamento de sessão.
9. Crie o trigger.

Use uma sessão reutilizada quando o trabalho se beneficia de continuidade, como briefings recorrentes. Use uma nova sessão por run quando cada execução deve ser independente.

## Criar um trigger webhook

1. Abra o agent no dashboard da Leme.
2. Vá para a aba **Triggers**.
3. Selecione **Novo trigger**.
4. Escolha **Webhook**.
5. Adicione um nome e uma instrução claros.
6. Escolha o comportamento de sessão.
7. Crie o trigger.
8. Copie a URL do webhook e o secret exibidos pela Leme.
9. Configure o sistema externo para enviar uma requisição `POST` para essa URL.

<Note>
  O secret do webhook é exibido quando o trigger é criado ou rotacionado. Salve-o no sistema externo antes de fechar o painel.
</Note>

Se o emissor permitir configurar headers, prefira enviar o secret assim:

```text theme={null}
Authorization: Bearer <secret>
```

Para evitar duplicidade, envie um identificador estável do evento:

```text theme={null}
Idempotency-Key: <event-id>
```

Os formatos suportados são JSON, texto puro e formulário URL-encoded. Mantenha payloads pequenos e inclua apenas os dados do evento que o agent precisa.

Eventos aceitos são respondidos imediatamente com `202` e um `statusUrl`:

```json theme={null}
{ "received": true, "duplicate": false, "runId": "...", "statusUrl": "/api/v1/runs/..." }
```

Para acompanhar o run a partir do seu sistema, consulte o `statusUrl` com um token de API — os status e o formato da resposta são os mesmos de [Executar agents via API](/pt-BR/api/runs#acompanhar-o-run).

## Testar um trigger

Use **Preview** para revisar a instrução que será enviada ao agent.

Use **Testar** para criar um run de teste real. Testes podem executar tools reais, pedir aprovações e afetar sistemas conectados, dependendo da configuração do agent.

## Histórico de runs

Cada trigger mostra runs recentes com status, horário, erros e links para a sessão ou task relacionada quando existir.

Payloads de webhook e secrets não são exibidos por completo. O dashboard mostra apenas resumos seguros para ajudar no troubleshooting.

## Troubleshooting

**Nenhum run aparece:** confirme que o trigger está ativo, que o agent está ativo e que o fuso horário do schedule está correto.

**Webhook é rejeitado:** verifique a URL, o secret, o content type e o tamanho do payload.

**Webhook aparece duplicado:** envie um `Idempotency-Key` estável para cada evento externo.

**Run está aguardando:** o agent pode estar aguardando uma aprovação humana obrigatória.

**Run falha depois de já ter funcionado:** confirme que o usuário que criou o trigger ainda tem acesso ao agent e às conexões necessárias.

**Trigger gera volume demais:** pause o trigger, ajuste o horário ou o sistema externo e depois reative.