Update triggers docs (#3678)

* docs: introduce triggers list & triggers run command * docs: add KO triggers docs
2026-01-09 08:08:32 +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/ko/enterprise/guides/automation-triggers.mdx
+++ b/docs/ko/enterprise/guides/automation-triggers.mdx
@@ -110,19 +110,49 @@ CrewAI AMP 트리거는 팀이 이미 사용하고 있는 도구의 실시간
 - `allow_crewai_trigger_context` 옵션으로 컨텍스트 자동 주입 여부를 결정했나요?
 - 웹훅 로그, CrewAI 실행 기록, 외부 알림 등 모니터링을 준비했나요?

-### Payload & Crew 예제 저장소
+### CLI로 로컬에서 트리거 테스트

-| 통합 | 동작 시점 | Payload 예제 | Crew 예제 |
-| :-- | :-- | :-- | :-- |
-| Gmail | 신규 메일, 스레드 업데이트 | [Gmail payload](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 | 이벤트 생성/수정/시작/종료/취소 | [Calendar payload](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 | 파일 생성/수정/삭제 | [Drive payload](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 | 새 이메일, 이벤트 제거 | [Outlook payload](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 | 파일 작업(생성, 수정, 공유, 삭제) | [OneDrive payload](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 | 레코드 생성/업데이트(연락처, 회사, 딜) | [HubSpot payload](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 | 채팅 생성 | [Teams payload](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) |
+CrewAI CLI는 프로덕션에 배포하기 전에 트리거 기반 자동화를 개발하고 테스트할 수 있는 강력한 명령을 제공합니다.

-예제 payload를 참고해 파싱 로직을 검증하고, 제공되는 crew를 복사해 실제 데이터로 교체하세요.
+#### 사용 가능한 트리거 목록 보기
+
+연결된 통합에 사용 가능한 모든 트리거를 확인하세요:
+
+```bash
+crewai triggers list
+```
+
+이 명령은 연결된 통합을 기반으로 사용 가능한 모든 트리거를 표시합니다:
+- 통합 이름 및 연결 상태
+- 사용 가능한 트리거 유형
+- 트리거 이름 및 설명
+
+#### 트리거 실행 시뮬레이션
+
+배포 전에 실제 트리거 payload로 크루를 테스트하세요:
+
+```bash
+crewai triggers run <트리거_이름>
+```
+
+예시:
+
+```bash
+crewai triggers run microsoft_onedrive/file_changed
+```
+
+이 명령은:
+- 로컬에서 크루를 실행합니다
+- 완전하고 실제적인 트리거 payload를 전달합니다
+- 프로덕션에서 크루가 호출되는 방식을 정확히 시뮬레이션합니다
+
+<Warning>
+  **중요한 개발 노트:**
+  - 개발 중 트리거 실행을 시뮬레이션하려면 `crewai triggers run <trigger>`를 사용하세요
+  - `crewai run`을 사용하면 트리거 호출을 시뮬레이션하지 않으며 트리거 payload를 전달하지 않습니다
+  - 배포 후에는 실제 트리거 payload로 크루가 실행됩니다
+  - 크루가 트리거 payload에 없는 매개변수를 기대하면 실행이 실패할 수 있습니다
+</Warning>

 ### 트리거와 Crew 연동

@@ -191,17 +221,20 @@ def delegate_to_crew(self, crewai_trigger_payload: dict = None):
 ## 문제 해결

 **트리거가 실행되지 않나요?**
- 트리거가 활성 상태인지 확인하세요.
- 통합 연결 상태를 확인하세요.
+- 배포의 Triggers 탭에서 트리거가 활성화되어 있는지 확인하세요
+- Tools & Integrations에서 통합 연결 상태를 확인하세요
+- 필요한 모든 환경 변수가 올바르게 구성되어 있는지 확인하세요

 **실행 중 오류가 발생하나요?**
- 실행 로그에서 오류 메시지를 확인하세요.
- 개발 중이라면 `crewai_trigger_payload`가 올바른 데이터로 전달되고 있는지 확인하세요.
+- 실행 로그에서 오류 세부 정보를 확인하세요
+- `crewai triggers run <트리거_이름>`을 사용하여 로컬에서 테스트하고 정확한 payload 구조를 확인하세요
+- 크루가 `crewai_trigger_payload` 매개변수를 처리할 수 있는지 확인하세요
+- 크루가 트리거 payload에 포함되지 않은 매개변수를 기대하지 않는지 확인하세요
+
+**개발 문제:**
+- 배포하기 전에 항상 `crewai triggers run <trigger>`로 테스트하여 전체 payload를 확인하세요
+- `crewai run`은 트리거 호출을 시뮬레이션하지 않으므로 `crewai triggers run`을 대신 사용하세요
+- `crewai triggers list`를 사용하여 연결된 통합에 사용 가능한 트리거를 확인하세요
+- 배포 후 크루는 실제 트리거 payload를 받으므로 먼저 로컬에서 철저히 테스트하세요

 트리거를 활용하면 CrewAI 자동화를 이벤트 기반 시스템으로 전환하여 기존 비즈니스 프로세스와 도구에 자연스럽게 녹여낼 수 있습니다.
-
-<Callout icon="github" title="예제 저장소">
-  <a href="https://github.com/crewAIInc/crewai-enterprise-trigger-examples">
-    CrewAI AMP Trigger Examples
-  </a>
-</Callout>
--- a/docs/ko/enterprise/guides/gmail-trigger.mdx
+++ b/docs/ko/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
+### 로컬에서 테스트

-The [CrewAI AMP Trigger Examples repository](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/gmail) includes:
+CrewAI CLI를 사용하여 Gmail 트리거 통합을 로컬에서 테스트하세요:

- `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
+# 사용 가능한 모든 트리거 보기
+crewai triggers list

-Use these samples to validate your parsing logic locally before wiring the trigger to your live Gmail accounts.
+# 실제 payload로 Gmail 트리거 시뮬레이션
+crewai triggers run gmail/new_email
+```
+
+`crewai triggers run` 명령은 완전한 Gmail payload로 크루를 실행하여 배포 전에 파싱 로직을 테스트할 수 있게 해줍니다.
+
+<Warning>
+  개발 중에는 `crewai triggers run gmail/new_email`을 사용하세요 (`crewai run`이 아님). 배포 후에는 크루가 자동으로 트리거 payload를 받습니다.
+</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
+- `crewai triggers run gmail/new_email`로 로컬 테스트하여 정확한 payload 구조를 확인하세요
 - Check the execution logs and confirm the payload is passed as `crewai_trigger_payload`
+- 주의: 트리거 실행을 시뮬레이션하려면 `crewai triggers run`을 사용하세요 (`crewai run`이 아님)
--- a/docs/ko/enterprise/guides/google-calendar-trigger.mdx
+++ b/docs/ko/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
+## 로컬에서 테스트

-The [Google Calendar examples](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/google_calendar) show how to handle multiple event types:
+CrewAI CLI를 사용하여 Google Calendar 트리거 통합을 로컬에서 테스트하세요:

- `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
+# 사용 가능한 모든 트리거 보기
+crewai triggers list

-Each crew transforms raw event metadata (attendees, rooms, working locations) into the summaries your teams need.
+# 실제 payload로 Google Calendar 트리거 시뮬레이션
+crewai triggers run google_calendar/event_changed
+```
+
+`crewai triggers run` 명령은 완전한 Calendar payload로 크루를 실행하여 배포 전에 파싱 로직을 테스트할 수 있게 해줍니다.
+
+<Warning>
+  개발 중에는 `crewai triggers run google_calendar/event_changed`를 사용하세요 (`crewai run`이 아님). 배포 후에는 크루가 자동으로 트리거 payload를 받습니다.
+</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
+- `crewai triggers run google_calendar/event_changed`로 로컬 테스트하여 정확한 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
+- 주의: 트리거 실행을 시뮬레이션하려면 `crewai triggers run`을 사용하세요 (`crewai run`이 아님)
--- a/docs/ko/enterprise/guides/google-drive-trigger.mdx
+++ b/docs/ko/enterprise/guides/google-drive-trigger.mdx
@@ -36,15 +36,23 @@ crew.kickoff({
 })
 ```

-## Sample payloads & crews
+## 로컬에서 테스트

-Explore the [Google Drive examples](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/google_drive) to cover different operations:
+CrewAI CLI를 사용하여 Google Drive 트리거 통합을 로컬에서 테스트하세요:

- `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
+# 사용 가능한 모든 트리거 보기
+crewai triggers list

-Each crew highlights the file name, operation type, owner, permissions, and security considerations so downstream systems can respond appropriately.
+# 실제 payload로 Google Drive 트리거 시뮬레이션
+crewai triggers run google_drive/file_changed
+```
+
+`crewai triggers run` 명령은 완전한 Drive payload로 크루를 실행하여 배포 전에 파싱 로직을 테스트할 수 있게 해줍니다.
+
+<Warning>
+  개발 중에는 `crewai triggers run google_drive/file_changed`를 사용하세요 (`crewai run`이 아님). 배포 후에는 크루가 자동으로 트리거 payload를 받습니다.
+</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
+- `crewai triggers run google_drive/file_changed`로 로컬 테스트하여 정확한 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
+- 주의: 트리거 실행을 시뮬레이션하려면 `crewai triggers run`을 사용하세요 (`crewai run`이 아님)
--- a/docs/ko/enterprise/guides/hubspot-trigger.mdx
+++ b/docs/ko/enterprise/guides/hubspot-trigger.mdx
@@ -49,6 +49,4 @@ mode: "wide"
    </Step>
 </Steps>

-## 추가 자료
-
 사용 가능한 작업과 사용자 지정 옵션에 대한 자세한 정보는 [HubSpot 워크플로우 문서](https://knowledge.hubspot.com/workflows/create-workflows)를 참고하세요.
--- a/docs/ko/enterprise/guides/microsoft-teams-trigger.mdx
+++ b/docs/ko/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
+## 로컬에서 테스트

-The [Microsoft Teams examples](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/microsoft-teams) include:
+CrewAI CLI를 사용하여 Microsoft Teams 트리거 통합을 로컬에서 테스트하세요:

- `chat-created.json` → chat creation payload processed by `teams-chat-created-crew.py`
+```bash
+# 사용 가능한 모든 트리거 보기
+crewai triggers list

-The crew demonstrates how to extract participants, initial messages, tenant information, and compliance metadata from the Microsoft Graph webhook payload.
+# 실제 payload로 Microsoft Teams 트리거 시뮬레이션
+crewai triggers run microsoft_teams/teams_message_created
+```
+
+`crewai triggers run` 명령은 완전한 Teams payload로 크루를 실행하여 배포 전에 파싱 로직을 테스트할 수 있게 해줍니다.
+
+<Warning>
+  개발 중에는 `crewai triggers run microsoft_teams/teams_message_created`를 사용하세요 (`crewai run`이 아님). 배포 후에는 크루가 자동으로 트리거 payload를 받습니다.
+</Warning>

 ## Troubleshooting

 - Ensure the Teams connection is active; it must be refreshed if the tenant revokes permissions
+- `crewai triggers run microsoft_teams/teams_message_created`로 로컬 테스트하여 정확한 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
+- 주의: 트리거 실행을 시뮬레이션하려면 `crewai triggers run`을 사용하세요 (`crewai run`이 아님)
--- a/docs/ko/enterprise/guides/onedrive-trigger.mdx
+++ b/docs/ko/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
+## 로컬에서 테스트

-The [OneDrive examples](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/onedrive) showcase how to:
+CrewAI CLI를 사용하여 OneDrive 트리거 통합을 로컬에서 테스트하세요:

- Parse file metadata, size, and folder paths
- Track who created and last modified the file
- Highlight permission and external sharing changes
+```bash
+# 사용 가능한 모든 트리거 보기
+crewai triggers list

-`onedrive-file-crew.py` bundles the analysis and summarization tasks so you can add remediation steps as needed.
+# 실제 payload로 OneDrive 트리거 시뮬레이션
+crewai triggers run microsoft_onedrive/file_changed
+```
+
+`crewai triggers run` 명령은 완전한 OneDrive payload로 크루를 실행하여 배포 전에 파싱 로직을 테스트할 수 있게 해줍니다.
+
+<Warning>
+  개발 중에는 `crewai triggers run microsoft_onedrive/file_changed`를 사용하세요 (`crewai run`이 아님). 배포 후에는 크루가 자동으로 트리거 payload를 받습니다.
+</Warning>

 ## Troubleshooting

 - Ensure the connected account has permission to read the file metadata included in the webhook
+- `crewai triggers run microsoft_onedrive/file_changed`로 로컬 테스트하여 정확한 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
+- 주의: 트리거 실행을 시뮬레이션하려면 `crewai triggers run`을 사용하세요 (`crewai run`이 아님)
--- a/docs/ko/enterprise/guides/outlook-trigger.mdx
+++ b/docs/ko/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
+## 로컬에서 테스트

-Review the [Outlook examples](https://github.com/crewAIInc/crewai-enterprise-trigger-examples/tree/main/outlook) for two common scenarios:
+CrewAI CLI를 사용하여 Outlook 트리거 통합을 로컬에서 테스트하세요:

- `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
+# 사용 가능한 모든 트리거 보기
+crewai triggers list

-Each crew demonstrates how to handle Microsoft Graph payloads, normalize headers, and keep humans in-the-loop with concise summaries.
+# 실제 payload로 Outlook 트리거 시뮬레이션
+crewai triggers run microsoft_outlook/email_received
+```
+
+`crewai triggers run` 명령은 완전한 Outlook payload로 크루를 실행하여 배포 전에 파싱 로직을 테스트할 수 있게 해줍니다.
+
+<Warning>
+  개발 중에는 `crewai triggers run microsoft_outlook/email_received`를 사용하세요 (`crewai run`이 아님). 배포 후에는 크루가 자동으로 트리거 payload를 받습니다.
+</Warning>

 ## Troubleshooting

 - Verify the Outlook connector is still authorized; the subscription must be renewed periodically
+- `crewai triggers run microsoft_outlook/email_received`로 로컬 테스트하여 정확한 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
+- 주의: 트리거 실행을 시뮬레이션하려면 `crewai triggers run`을 사용하세요 (`crewai run`이 아님)