crewAI/TRIGGER_IMPLEMENTATION_SUMMARY.md

CrewAI CLI Trigger Feature Implementation

Overview

Successfully implemented the trigger functionality for CrewAI CLI as requested, adding two main commands:

• crewai trigger list - Lists all triggers grouped by provider
• crewai trigger <app/trigger_name> - Runs a crew with the specified trigger payload

Implementation Details

1. Extended PlusAPI Client (src/crewai/cli/plus_api.py)

• Added TRIGGERS_RESOURCE = "/v1/triggers" endpoint constant
• Implemented list_triggers() method for GET /v1/triggers
• Implemented get_trigger_sample_payload(trigger_identification) method for POST /v1/triggers/sample_payload

2. Created TriggerCommand Class (src/crewai/cli/trigger_command.py)

• Inherits from BaseCommand and PlusAPIMixin for proper authentication
• Implements list_triggers() method with:
  • Rich table display grouped by provider
  • Comprehensive error handling for network issues, authentication, etc.
  • User-friendly messages and styling
• Implements run_trigger(trigger_identification) method with:
  • Trigger identification format validation (app/trigger_name)
  • Sample payload retrieval from API
  • Dynamic crew/flow execution with trigger payload injection
  • Temporary script generation and cleanup
  • Robust error handling and validation

3. Integrated CLI Commands (src/crewai/cli/cli.py)

• Added import for TriggerCommand
• Implemented @crewai.command() decorator for trigger command
• Supports both crewai trigger list and crewai trigger <app/trigger_name> syntax
• Proper argument parsing and command routing

4. Key Features

Trigger Listing

• Fetches triggers from /v1/triggers endpoint
• Displays triggers in a formatted table grouped by provider
• Shows trigger ID and description for each trigger
• Provides usage instructions

Trigger Execution

• Validates trigger identification format
• Fetches sample payload from /v1/triggers/sample_payload endpoint
• Detects project type (crew vs flow) from pyproject.toml
• Generates appropriate execution script with trigger payload injection
• Executes crew/flow with uv run python command
• Adds trigger payload to inputs as crewai_trigger_payload
• Handles cleanup of temporary files

Error Handling

• Network connectivity issues
• Authentication failures (401)
• Authorization issues (403)
• Trigger not found (404)
• Invalid project structure
• Subprocess execution errors
• Comprehensive user feedback with actionable suggestions

5. Usage Examples

# List all available triggers
crewai trigger list

# Run a specific trigger
crewai trigger github/pull_request_opened
crewai trigger slack/message_received
crewai trigger webhook/user_signup

6. API Integration Points

CrewAI Client → Rails App

• GET /v1/triggers - Returns triggers grouped by provider
• POST /v1/triggers/sample_payload with {"trigger_identification": "app/trigger_name"}

Expected Response Format

{
  "github": {
    "github/pull_request_opened": {
      "description": "Triggered when a pull request is opened"
    },
    "github/issue_created": {
      "description": "Triggered when an issue is created"
    }
  },
  "slack": {
    "slack/message_received": {
      "description": "Triggered when a message is received"
    }
  }
}

7. Crew/Flow Integration

The trigger payload is automatically injected into the crew/flow inputs as crewai_trigger_payload, allowing crews to access trigger data:

# In crew/flow code
def my_crew():
    crew = Crew(...)
    result = crew.kickoff(inputs=inputs)  # inputs will contain 'crewai_trigger_payload'
    return result

8. Dependencies

• click - CLI framework
• rich - Enhanced terminal output
• requests - HTTP client
• Existing CrewAI CLI infrastructure (authentication, configuration, etc.)

Testing

• All imports work correctly
• CLI command structure is properly implemented
• Error handling is comprehensive
• Code follows CrewAI patterns and conventions

Next Steps for Backend Implementation

Rails App Requirements

1. Add GET /v1/triggers endpoint
2. Add POST /v1/triggers/sample_payload endpoint
3. Implement integration service method summarize_triggers
4. Each provider service must implement:
   • list_triggers() method
   • get_sample_payload(trigger_identification) method

CrewAI OAuth Requirements

1. Implement endpoint that returns sample payload for trigger identification
2. Ensure trigger data format matches expected structure

The CLI implementation is complete and ready for integration with the backend services.