Automation Configuration

Automations allow external systems to trigger AI agents and teams through a webhook-style interface with pattern matching. When an event matches the configured pattern, the automation sends a message to the designated agent or team.

What are Automations?

Automations (also called Event Listeners) are configurations that:

1. Listen for events sent to your webhook endpoint
2. Match incoming events against configured patterns
3. Trigger agents or teams when patterns match
4. Send templated messages constructed from event data

Core Concepts

Event Pattern Matching

Events are matched using the event_pattern field:

• Exact Match: Matches the exact event type string (order.created)
• Prefix Match: Matches event types starting with the pattern (order. matches order.created, order.updated)
• Wildcard Match: Uses fnmatch syntax (order.* matches order.created but not order.item.added)

Target Types

Automations can trigger:

• Agent: Direct message to a specific agent
• Team: Message to a team (routed through team's orchestrator)

Message Templates

Templates use Jinja2 syntax to construct messages from event data:

New order received: {{ payload.order_id }}
Customer: {{ payload.customer_name }}
Total: ${{ payload.total }}

Automation List Page

Access at /automations to view and manage all automations.

Features

• Search: Filter by name, event pattern, or description
• Type Filter: Filter by target type (Agent/Team)
• Status Filter: Active/Inactive automations
• Pattern Match Filter: Filter by match type
• Quick Actions: Edit, test, enable/disable, delete

Columns

Column	Description
Name	Automation display name
Event Pattern	Pattern to match (e.g., order.*)
Match Type	Exact, Prefix, or Wildcard
Target	Agent or Team name
Priority	Execution priority (1=Critical, 10=Low)
Status	Active/Inactive indicator
Executions	Count of times triggered
Last Executed	Timestamp of last execution
Actions	Edit, delete buttons

Creating Automations

Navigate to /automations/create to create a new automation.

Basic Settings

Field	Required	Description
Name	Yes	Human-readable name for the automation
Identifier	No	Auto-generated URL-friendly slug
Description	No	Purpose and usage notes

Trigger Configuration

Event Pattern

Enter the event type pattern to match:

order.created        # Exact match
order.              # Prefix match
order.*             # Wildcard match
user.*.created      # Wildcard in middle

Match Type

Choose how the pattern is matched:

Match Type	Description	Example Pattern	Matches	Doesn't Match
Exact	Exact string match	order.created	order.created	order.updated, order.created.v2
Prefix	Starts with pattern	order.	order.created, order.updated	orders.created
Wildcard	Pattern matching with *	order.*	order.created, order.updated	order.item.added

Pattern Matching Rules

• * matches any characters except . (single level)
• ** matches any characters including . (multiple levels)
• Prefix match is fastest, use when possible

Action Configuration

Target Selection

Choose what to trigger when the event matches:

1. Target Type: Select "Agent" or "Team"
2. Select Resource:
   • For Agent: Choose from your agents
   • For Team: Choose from your teams
3. The selected resource will receive the templated message

Message Template

Create a Jinja2 template to construct the message sent to the agent/team:

New {{ event_type }} event received!

Event Details:
- Type: {{ event_type }}
- ID: {{ payload.id }}
- Status: {{ payload.status }}

{% if context.source %}
Source: {{ context.source }}
{% endif %}

Please process this event and respond with next steps.

Template Variables

Available variables in message templates:

Variable	Type	Description	Example
event_type	string	The event type string	"order.created"
payload	object	The event payload data	{"order_id": "123", "total": 99.99}
payload.field	any	Access specific payload field	payload.order_id → "123"
context	object	Optional context metadata	{"source": "shopify", "env": "prod"}
context.field	any	Access specific context field	context.source → "shopify"

Template Example

Event received:

{
  "event_type": "order.created",
  "payload": {
    "order_id": "ORD-123",
    "customer_name": "Jane Smith",
    "total": 149.99,
    "items": 3
  },
  "context": {
    "source": "shopify",
    "environment": "production"
  }
}

Template:

New order from {{ payload.customer_name }}!

Order ID: {{ payload.order_id }}
Total: ${{ payload.total }}
Items: {{ payload.items }}

Source: {{ context.source }}
Environment: {{ context.environment }}

Please review this order and respond with any concerns.

Rendered message:

New order from Jane Smith!

Order ID: ORD-123
Total: $149.99
Items: 3

Source: shopify
Environment: production

Please review this order and respond with any concerns.

Priority Configuration

Set execution priority when multiple automations match:

Priority Value	Label	Description
1	Critical	Process first, highest importance
2	High	Process early, important
3	Above Normal	Slightly elevated priority
5	Normal	Standard processing order (default)
7	Below Normal	Can wait for higher priority
10	Low	Process last, background tasks

Lower numbers execute first. Use Critical (1) for urgent events like security alerts.

Advanced Settings

Click Advanced Settings to configure:

Setting	Default	Description
Timeout (seconds)	60	Maximum time for agent/team to respond
Retry Count	3	Number of retry attempts on failure

Status

Toggle Active/Inactive:

• Active: Automation processes matching events
• Inactive: Events are received but not processed (useful for testing)

Editing Automations

1. Navigate to /automations
2. Click Edit on the automation
3. Modify settings as needed
4. Click Save

Changes take effect immediately for new events.

Testing Automations

Test Template Rendering

Use the template test interface:

1. Open automation edit page
2. Click Test Template
3. Enter sample event data:

   {
     "event_type": "test.event",
     "payload": {
       "test_field": "test value"
     },
     "context": {
       "source": "manual-test"
     }
   }

4. Preview rendered message
5. Verify variables are substituted correctly

Test with Real Events

1. Set automation to Inactive first
2. Send test events to your webhook endpoint
3. Review automation execution logs
4. Verify pattern matching works as expected
5. Set to Active when ready

Execution History

View execution history on the automation detail page:

Column	Description
Timestamp	When the event was received
Event Type	The event type that matched
Status	Pending, Running, Completed, Failed, Timeout
Message Sent	The rendered template sent to agent/team
Response	Agent/team response (if completed)
Duration	How long execution took
Attempt	Retry attempt number (1 for first try)

Execution Statuses

• Pending: Event matched, waiting to execute
• Running: Agent/team is currently processing
• Completed: Successfully processed and responded
• Failed: Execution failed (check error message)
• Timeout: Exceeded configured timeout

Webhook Integration

Webhook Endpoint

Your automation webhook endpoint:

POST https://your-gnosari-domain.com/api/v1/events

Authentication

Include your API key in the Authorization header:

curl -X POST https://your-gnosari-domain.com/api/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "order.created",
    "payload": {
      "order_id": "123",
      "total": 99.99
    }
  }'

Event Payload Structure

{
  "event_type": "your.event.type",
  "payload": {
    // Your event data
  },
  "context": {
    // Optional metadata
  }
}

Required fields:

• event_type (string): The event type to match

Optional fields:

• payload (object): Event data accessible in templates
• context (object): Metadata accessible in templates

Common Use Cases

E-commerce Order Processing

Event Pattern: order.createdMatch Type: Exact Target: Customer Service Team Priority: High (2)

Template:

New order received: {{ payload.order_id }}

Customer: {{ payload.customer_name }}
Email: {{ payload.customer_email }}
Total: ${{ payload.total }}

Please review and confirm processing.

Support Ticket Escalation

Event Pattern: ticket.escalatedMatch Type: Exact Target: Senior Support Agent Priority: Critical (1)

Template:

URGENT: Ticket {{ payload.ticket_id }} escalated

Priority: {{ payload.priority }}
Customer: {{ payload.customer_name }}
Issue: {{ payload.subject }}

Original assignee: {{ context.previous_agent }}
Escalation reason: {{ payload.escalation_reason }}

Please review immediately.

User Signup Welcome

Event Pattern: user.signupMatch Type: Exact Target: Onboarding Bot Priority: Normal (5)

Template:

Welcome new user: {{ payload.name }}

Email: {{ payload.email }}
Signup source: {{ context.source }}
Plan: {{ payload.plan_name }}

Send welcome email and start onboarding flow.

Payment Failure

Event Pattern: payment.failedMatch Type: Exact Target: Billing Support Team Priority: High (2)

Template:

Payment failed for {{ payload.customer_name }}

Amount: ${{ payload.amount }}
Card ending in: {{ payload.last_4 }}
Reason: {{ payload.failure_reason }}

Please reach out to customer and assist with payment issue.

Best Practices

Event Pattern Design

• Use exact match for known, specific events
• Use prefix match for event families (order., user.)
• Test patterns with sample events before going live

Template Writing

• Include context: Event type, key identifiers, timestamps
• Be specific: Give agent/team clear action items
• Format clearly: Use line breaks, bullet points
• Handle missing data: Use Jinja2 conditionals for optional fields

{% if payload.customer_email %}
Email: {{ payload.customer_email }}
{% else %}
Email: Not provided
{% endif %}

Priority Assignment

• Critical (1-2): Security alerts, payment failures, urgent escalations
• Normal (3-7): Standard events, routine processing
• Low (8-10): Analytics, logging, background tasks

Error Handling

• Set appropriate timeouts: Longer for complex agent interactions
• Configure retries: 3 retries is good for transient failures
• Monitor execution logs: Review failures regularly
• Test inactive first: Always test with inactive status before enabling

Troubleshooting

Automation Not Triggering

1. Check status: Ensure automation is Active
2. Verify pattern: Test pattern matching with sample events
3. Check logs: Review webhook request logs for errors
4. Validate payload: Ensure event_type field is present

Template Variables Not Rendering

1. Check JSON structure: Verify payload/context structure matches template
2. Use dot notation: payload.field not payload['field']
3. Test template: Use template test feature with sample data
4. Check for typos: Variable names are case-sensitive

Execution Failures

1. Review error message: Check execution history for details
2. Verify target: Ensure agent/team exists and is active
3. Check timeout: Increase if agent needs more processing time
4. Test agent directly: Verify agent can handle the message type

High Priority Not Working

1. Check priority values: Lower numbers execute first (1 is highest)
2. Review execution order: Check logs to verify order
3. Verify multiple matches: Ensure patterns don't conflict