Triggers

Triggers provide webhook endpoints for external systems to invoke your agents.

API Endpoints

Execute Trigger

POST /v1/formations/{formation_id}/triggers/{trigger_name}

Headers:

Request Body:

{
  "data": {
    "key": "value",
    "nested": {
      "property": "value"
    }
  },
  "session_id": "optional-session-id",
  "use_async": true
}

Response (Async):

{
  "object": "request",
  "type": "request.processing",
  "request": {"id": "req_abc123"},
  "success": true,
  "data": {"status": "processing"}
}

Response (Sync):

{
  "object": "request",
  "type": "request.completed",
  "request": {"id": "req_abc123"},
  "success": true,
  "data": {
    "status": "completed",
    "response": "Agent's response text..."
  }
}

List Triggers

GET /v1/formations/{formation_id}/triggers

Response:

{
  "object": "list",
  "data": {
    "formation_id": "my-formation",
    "triggers": ["github-issue", "slack-message"],
    "count": 2
  }
}

Template Syntax

Templates use ${{ data.* }} for variable substitution:

${{ data.name }}                    # Simple access
${{ data.issue.number }}            # Nested access
${{ data.user.profile.name }}       # Multi-level nesting

Directory Structure

triggers/
├── github-issue.md
├── slack-message.md
├── stripe-payment.md
└── monitoring-alert.md

Templates are auto-discovered from triggers/ directory.

Request Options

Error Responses

Template Rendering Error

{
  "object": "error",
  "type": "error.validation",
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Template rendering failed: Key 'data.issue.number' not found"
  }
}

Trigger Not Found

{
  "object": "error",
  "type": "error.not_found",
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Trigger template 'unknown' not found"
  }
}

Example: Complete Workflow

1. Create Template

<!-- triggers/github-issue.md -->
New issue from ${{ data.repository }}:

**#${{ data.issue.number }}**: ${{ data.issue.title }}

${{ data.issue.body }}

Please triage this issue.

2. Configure GitHub Webhook

• URL: https://your-server/v1/formations/my-formation/triggers/github-issue
• Content type: application/json
• Events: Issues

3. Test with curl

curl -X POST http://localhost:8001/v1/formations/my-formation/triggers/github-issue \
  -H "X-Muxi-Client-Key: fmc_..." \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "repository": "muxi/runtime",
      "issue": {
        "number": 123,
        "title": "Bug report",
        "body": "Description..."
      }
    },
    "use_async": false
  }'

Related

• Triggers & Webhooks - Concept overview
• Create Triggers - Step-by-step guide
• Async Processing - Async mode details