Update triggers docs (#3678)

* docs: introduce triggers list & triggers run command * docs: add KO triggers docs
2026-01-11 09:08:31 +00:00 · 2025-10-09 16:11:57 -03:00
parent 0648e88f22
commit da331ce422
24 changed files with 462 additions and 205 deletions
--- a/docs/pt-BR/enterprise/guides/automation-triggers.mdx
+++ b/docs/pt-BR/enterprise/guides/automation-triggers.mdx
@@ -116,19 +116,49 @@ Antes de ativar em produção, confirme que você:
 - Decidiu se usará `allow_crewai_trigger_context` para injetar contexto automaticamente
 - Configurou monitoramento (webhooks, históricos da CrewAI, alertas externos)

-### Repositório de Payloads e Crews de Exemplo
+### Testando Triggers Localmente com CLI

-| Integração | Quando dispara | Amostras de payload | Crews de exemplo |
-| :-- | :-- | :-- | :-- |
-| Gmail | Novas mensagens, atualização de threads | [Payloads de alertas e threads](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/gmail) | [`new-email-crew.py`, `gmail-alert-crew.py`](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/gmail) |
-| Google Calendar | Evento criado/atualizado/iniciado/encerrado/cancelado | [Payloads de eventos](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/google_calendar) | [`calendar-event-crew.py`, `calendar-meeting-crew.py`, `calendar-working-location-crew.py`](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/google_calendar) |
-| Google Drive | Arquivo criado/atualizado/excluído | [Payloads de arquivos](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/google_drive) | [`drive-file-crew.py`, `drive-file-deletion-crew.py`](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/google_drive) |
-| Outlook | Novo e‑mail, evento removido | [Payloads do Outlook](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/outlook) | [`outlook-message-crew.py`, `outlook-event-removal-crew.py`](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/outlook) |
-| OneDrive | Operações de arquivo (criar, atualizar, compartilhar, excluir) | [Payloads do OneDrive](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/onedrive) | [`onedrive-file-crew.py`](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/onedrive) |
-| HubSpot | Registros criados/atualizados (contatos, empresas, negócios) | [Payloads do HubSpot](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/hubspot) | [`hubspot-company-crew.py`, `hubspot-contact-crew.py`, `hubspot-record-crew.py`](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/hubspot) |
-| Microsoft Teams | Chat criado | [Payload do Teams](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/microsoft-teams) | [`teams-chat-created-crew.py`](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/microsoft-teams) |
+A CLI da CrewAI fornece comandos poderosos para ajudá-lo a desenvolver e testar automações orientadas por triggers sem fazer deploy para produção.

-Use essas amostras para ajustar o parsing, copiar a crew correspondente e substituir o payload de teste pelo dado real.
+#### Listar Triggers Disponíveis
+
+Visualize todos os triggers disponíveis para suas integrações conectadas:
+
+```bash
+crewai triggers list
+```
+
+Este comando exibe todos os triggers disponíveis baseados nas suas integrações conectadas, mostrando:
+- Nome da integração e status de conexão
+- Tipos de triggers disponíveis
+- Nomes e descrições dos triggers
+
+#### Simular Execução de Trigger
+
+Teste sua crew com payloads realistas de triggers antes do deployment:
+
+```bash
+crewai triggers run <nome_do_trigger>
+```
+
+Por exemplo:
+
+```bash
+crewai triggers run microsoft_onedrive/file_changed
+```
+
+Este comando:
+- Executa sua crew localmente
+- Passa um payload de trigger completo e realista
+- Simula exatamente como sua crew será chamada em produção
+
+<Warning>
+  **Notas Importantes de Desenvolvimento:**
+  - Use `crewai triggers run <trigger>` para simular execução de trigger durante o desenvolvimento
+  - Usar `crewai run` NÃO simulará chamadas de trigger e não passará o payload do trigger
+  - Após o deployment, sua crew será executada com o payload real do trigger
+  - Se sua crew espera parâmetros que não estão no payload do trigger, a execução pode falhar
+</Warning>

 ### Triggers com Crews

@@ -203,17 +233,20 @@ def delegar_para_crew(self, crewai_trigger_payload: dict = None):
 ## Solução de Problemas

 **Trigger não dispara:**
- Verifique se está habilitado
- Confira o status da conexão
+- Verifique se o trigger está habilitado na aba Triggers do seu deployment
+- Confira o status da conexão em Tools & Integrations
+- Garanta que todas as variáveis de ambiente necessárias estão configuradas

 **Falhas de execução:**
- Consulte os logs para entender o erro
- Durante o desenvolvimento, garanta que `crewai_trigger_payload` está presente com o payload correto
+- Consulte os logs de execução para detalhes do erro
+- Use `crewai triggers run <nome_do_trigger>` para testar localmente e ver a estrutura exata do payload
+- Verifique se sua crew pode processar o parâmetro `crewai_trigger_payload`
+- Garanta que sua crew não espera parâmetros que não estão incluídos no payload do trigger
+
+**Problemas de desenvolvimento:**
+- Sempre teste com `crewai triggers run <trigger>` antes de fazer deploy para ver o payload completo
+- Lembre-se que `crewai run` NÃO simula chamadas de trigger—use `crewai triggers run` em vez disso
+- Use `crewai triggers list` para verificar quais triggers estão disponíveis para suas integrações conectadas
+- Após o deployment, sua crew receberá o payload real do trigger, então teste minuciosamente localmente primeiro

 Os triggers transformam suas implantações CrewAI em sistemas orientados por eventos, integrando-se perfeitamente aos processos e ferramentas já usados pelo seu time.
-
-<Callout icon="github" title="Exemplos na prática">
-  <a href="https://github.com/crewAIInc/crewai-enterprise-trigger-examples">
-    Repositório CrewAI AMP Trigger Examples
-  </a>
-</Callout>
--- a/docs/pt-BR/enterprise/guides/gmail-trigger.mdx
+++ b/docs/pt-BR/enterprise/guides/gmail-trigger.mdx
@@ -51,16 +51,25 @@ class GmailProcessingCrew:
        )
 ```

-The Gmail payload will be available via the standard context mechanisms. See the payload samples repository for structure and fields.
+The Gmail payload will be available via the standard context mechanisms.

-### Sample payloads & crews
+### Testando Localmente

-The [CrewAI AMP Trigger Examples repository](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/gmail) includes:
+Teste sua integração de trigger do Gmail localmente usando a CLI da CrewAI:

- `new-email-payload-1.json` / `new-email-payload-2.json` — production-style new message alerts with matching crews in `new-email-crew.py`
- `thread-updated-sample-1.json` — follow-up messages on an existing thread, processed by `gmail-alert-crew.py`
+```bash
+# Visualize todos os triggers disponíveis
+crewai triggers list

-Use these samples to validate your parsing logic locally before wiring the trigger to your live Gmail accounts.
+# Simule um trigger do Gmail com payload realista
+crewai triggers run gmail/new_email
+```
+
+O comando `crewai triggers run` executará sua crew com um payload completo do Gmail, permitindo que você teste sua lógica de parsing antes do deployment.
+
+<Warning>
+  Use `crewai triggers run gmail/new_email` (não `crewai run`) para simular execução de trigger durante o desenvolvimento. Após o deployment, sua crew receberá automaticamente o payload do trigger.
+</Warning>

 ## Monitoring Executions

@@ -70,16 +79,10 @@ Track history and performance of triggered runs:
  <img src="/images/enterprise/list-executions.png" alt="List of executions triggered by automation" />
 </Frame>

-## Payload Reference
-
-See the sample payloads and field descriptions:
-
-<Card title="Gmail samples in Trigger Examples Repo" href="https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/gmail" icon="envelopes-bulk">
-    Gmail samples in Trigger Examples Repo
-</Card>
-
 ## Troubleshooting

 - Ensure Gmail is connected in Tools & Integrations
 - Verify the Gmail Trigger is enabled on the Triggers tab
+- Teste localmente com `crewai triggers run gmail/new_email` para ver a estrutura exata do payload
 - Check the execution logs and confirm the payload is passed as `crewai_trigger_payload`
+- Lembre-se: use `crewai triggers run` (não `crewai run`) para simular execução de trigger
--- a/docs/pt-BR/enterprise/guides/google-calendar-trigger.mdx
+++ b/docs/pt-BR/enterprise/guides/google-calendar-trigger.mdx
@@ -39,16 +39,23 @@ print(result.raw)

 Use `crewai_trigger_payload` exactly as it is delivered by the trigger so the crew can extract the proper fields.

-## Sample payloads & crews
+## Testando Localmente

-The [Google Calendar examples](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/google_calendar) show how to handle multiple event types:
+Teste sua integração de trigger do Google Calendar localmente usando a CLI da CrewAI:

- `new-event.json` → standard event creation handled by `calendar-event-crew.py`
- `event-updated.json` / `event-started.json` / `event-ended.json` → in-flight updates processed by `calendar-meeting-crew.py`
- `event-canceled.json` → cancellation workflow that alerts attendees via `calendar-meeting-crew.py`
- Working location events use `calendar-working-location-crew.py` to extract on-site schedules
+```bash
+# Visualize todos os triggers disponíveis
+crewai triggers list

-Each crew transforms raw event metadata (attendees, rooms, working locations) into the summaries your teams need.
+# Simule um trigger do Google Calendar com payload realista
+crewai triggers run google_calendar/event_changed
+```
+
+O comando `crewai triggers run` executará sua crew com um payload completo do Calendar, permitindo que você teste sua lógica de parsing antes do deployment.
+
+<Warning>
+  Use `crewai triggers run google_calendar/event_changed` (não `crewai run`) para simular execução de trigger durante o desenvolvimento. Após o deployment, sua crew receberá automaticamente o payload do trigger.
+</Warning>

 ## Monitoring Executions

@@ -61,5 +68,7 @@ The **Executions** list in the deployment dashboard tracks every triggered run a
 ## Troubleshooting

 - Ensure the correct Google account is connected and the trigger is enabled
+- Teste localmente com `crewai triggers run google_calendar/event_changed` para ver a estrutura exata do payload
 - Confirm your workflow handles all-day events (payloads use `start.date` and `end.date` instead of timestamps)
 - Check execution logs if reminders or attendee arrays are missing—calendar permissions can limit fields in the payload
+- Lembre-se: use `crewai triggers run` (não `crewai run`) para simular execução de trigger
--- a/docs/pt-BR/enterprise/guides/google-drive-trigger.mdx
+++ b/docs/pt-BR/enterprise/guides/google-drive-trigger.mdx
@@ -36,15 +36,23 @@ crew.kickoff({
 })
 ```

-## Sample payloads & crews
+## Testando Localmente

-Explore the [Google Drive examples](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/google_drive) to cover different operations:
+Teste sua integração de trigger do Google Drive localmente usando a CLI da CrewAI:

- `new-file.json` → new uploads processed by `drive-file-crew.py`
- `updated-file.json` → file edits and metadata changes handled by `drive-file-crew.py`
- `deleted-file.json` → deletion events routed through `drive-file-deletion-crew.py`
+```bash
+# Visualize todos os triggers disponíveis
+crewai triggers list

-Each crew highlights the file name, operation type, owner, permissions, and security considerations so downstream systems can respond appropriately.
+# Simule um trigger do Google Drive com payload realista
+crewai triggers run google_drive/file_changed
+```
+
+O comando `crewai triggers run` executará sua crew com um payload completo do Drive, permitindo que você teste sua lógica de parsing antes do deployment.
+
+<Warning>
+  Use `crewai triggers run google_drive/file_changed` (não `crewai run`) para simular execução de trigger durante o desenvolvimento. Após o deployment, sua crew receberá automaticamente o payload do trigger.
+</Warning>

 ## Monitoring Executions

@@ -57,5 +65,7 @@ Track history and performance of triggered runs with the **Executions** list in
 ## Troubleshooting

 - Verify Google Drive is connected and the trigger toggle is enabled
+- Teste localmente com `crewai triggers run google_drive/file_changed` para ver a estrutura exata do payload
 - If a payload is missing permission data, ensure the connected account has access to the file or folder
 - The trigger sends file IDs only; use the Drive API if you need to fetch binary content during the crew run
+- Lembre-se: use `crewai triggers run` (não `crewai run`) para simular execução de trigger
--- a/docs/pt-BR/enterprise/guides/microsoft-teams-trigger.mdx
+++ b/docs/pt-BR/enterprise/guides/microsoft-teams-trigger.mdx
@@ -37,16 +37,28 @@ print(result.raw)

 The crew parses thread metadata (subject, created time, roster) and generates an action plan for the receiving team.

-## Sample payloads & crews
+## Testando Localmente

-The [Microsoft Teams examples](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/microsoft-teams) include:
+Teste sua integração de trigger do Microsoft Teams localmente usando a CLI da CrewAI:

- `chat-created.json` → chat creation payload processed by `teams-chat-created-crew.py`
+```bash
+# Visualize todos os triggers disponíveis
+crewai triggers list

-The crew demonstrates how to extract participants, initial messages, tenant information, and compliance metadata from the Microsoft Graph webhook payload.
+# Simule um trigger do Microsoft Teams com payload realista
+crewai triggers run microsoft_teams/teams_message_created
+```
+
+O comando `crewai triggers run` executará sua crew com um payload completo do Teams, permitindo que você teste sua lógica de parsing antes do deployment.
+
+<Warning>
+  Use `crewai triggers run microsoft_teams/teams_message_created` (não `crewai run`) para simular execução de trigger durante o desenvolvimento. Após o deployment, sua crew receberá automaticamente o payload do trigger.
+</Warning>

 ## Troubleshooting

 - Ensure the Teams connection is active; it must be refreshed if the tenant revokes permissions
+- Teste localmente com `crewai triggers run microsoft_teams/teams_message_created` para ver a estrutura exata do payload
 - Confirm the webhook subscription in Microsoft 365 is still valid if payloads stop arriving
 - Review execution logs for payload shape mismatches—Graph notifications may omit fields when a chat is private or restricted
+- Lembre-se: use `crewai triggers run` (não `crewai run`) para simular execução de trigger
--- a/docs/pt-BR/enterprise/guides/onedrive-trigger.mdx
+++ b/docs/pt-BR/enterprise/guides/onedrive-trigger.mdx
@@ -36,18 +36,28 @@ crew.kickoff({

 The crew inspects file metadata, user activity, and permission changes to produce a compliance-friendly summary.

-## Sample payloads & crews
+## Testando Localmente

-The [OneDrive examples](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/onedrive) showcase how to:
+Teste sua integração de trigger do OneDrive localmente usando a CLI da CrewAI:

- Parse file metadata, size, and folder paths
- Track who created and last modified the file
- Highlight permission and external sharing changes
+```bash
+# Visualize todos os triggers disponíveis
+crewai triggers list

-`onedrive-file-crew.py` bundles the analysis and summarization tasks so you can add remediation steps as needed.
+# Simule um trigger do OneDrive com payload realista
+crewai triggers run microsoft_onedrive/file_changed
+```
+
+O comando `crewai triggers run` executará sua crew com um payload completo do OneDrive, permitindo que você teste sua lógica de parsing antes do deployment.
+
+<Warning>
+  Use `crewai triggers run microsoft_onedrive/file_changed` (não `crewai run`) para simular execução de trigger durante o desenvolvimento. Após o deployment, sua crew receberá automaticamente o payload do trigger.
+</Warning>

 ## Troubleshooting

 - Ensure the connected account has permission to read the file metadata included in the webhook
+- Teste localmente com `crewai triggers run microsoft_onedrive/file_changed` para ver a estrutura exata do payload
 - If the trigger fires but the payload is missing `permissions`, confirm the site-level sharing settings allow Graph to return this field
 - For large tenants, filter notifications upstream so the crew only runs on relevant directories
+- Lembre-se: use `crewai triggers run` (não `crewai run`) para simular execução de trigger
--- a/docs/pt-BR/enterprise/guides/outlook-trigger.mdx
+++ b/docs/pt-BR/enterprise/guides/outlook-trigger.mdx
@@ -36,17 +36,28 @@ crew.kickoff({

 The crew extracts sender details, subject, body preview, and attachments before generating a structured response.

-## Sample payloads & crews
+## Testando Localmente

-Review the [Outlook examples](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/outlook) for two common scenarios:
+Teste sua integração de trigger do Outlook localmente usando a CLI da CrewAI:

- `new-message.json` → new mail notifications parsed by `outlook-message-crew.py`
- `event-removed.json` → calendar cleanup handled by `outlook-event-removal-crew.py`
+```bash
+# Visualize todos os triggers disponíveis
+crewai triggers list

-Each crew demonstrates how to handle Microsoft Graph payloads, normalize headers, and keep humans in-the-loop with concise summaries.
+# Simule um trigger do Outlook com payload realista
+crewai triggers run microsoft_outlook/email_received
+```
+
+O comando `crewai triggers run` executará sua crew com um payload completo do Outlook, permitindo que você teste sua lógica de parsing antes do deployment.
+
+<Warning>
+  Use `crewai triggers run microsoft_outlook/email_received` (não `crewai run`) para simular execução de trigger durante o desenvolvimento. Após o deployment, sua crew receberá automaticamente o payload do trigger.
+</Warning>

 ## Troubleshooting

 - Verify the Outlook connector is still authorized; the subscription must be renewed periodically
+- Teste localmente com `crewai triggers run microsoft_outlook/email_received` para ver a estrutura exata do payload
 - If attachments are missing, confirm the webhook subscription includes the `includeResourceData` flag
 - Review execution logs when events fail to match—cancellation payloads lack attendee lists by design and the crew should account for that
+- Lembre-se: use `crewai triggers run` (não `crewai run`) para simular execução de trigger