CrewAIIntermediate20 min

CrewAI + HatiData: Semantic Trigger Setup

Configure semantic triggers that fire webhooks when CrewAI agents discuss specific topics. Use vector-based concept matching for intelligent alerting.

What You'll Build

A CrewAI multi-agent team with semantic triggers that fire webhooks when agents discuss specific topics.

Prerequisites

$pip install crewai hatidata-agent

$hati init

$OpenAI API key

$Webhook endpoint (e.g., webhook.site)

Architecture

┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  CrewAI      │───▶│  HatiData    │───▶│ Vector Index │
│  Agents      │    │  Triggers    │    │  Pre-filter   │
└──────────────┘    └──────────────┘    └──────────────┘
                          │
                          ▼
                    ┌──────────────┐
                    │   Webhook    │
                    │  (HMAC-256)  │
                    └──────────────┘

Key Concepts

●Semantic matching: triggers use vector ANN pre-filtering followed by exact cosine verification for accurate concept detection
●HMAC-SHA256 webhooks: all webhook payloads are signed so receivers can verify authenticity
●Cooldown debounce: triggers include configurable cooldown periods to prevent alert fatigue from repeated mentions
●Threshold tuning: use test_trigger() to find the right similarity threshold before deploying to production

Step-by-Step Implementation

Install Dependencies

Install CrewAI and the HatiData agent SDK.

Bash

pip install crewai hatidata-agent
hati init

Expected Output

HatiData initialized successfully.
Proxy running on localhost:5439
MCP server running on localhost:5440

Note: Semantic triggers use a vector search engine for concept matching. The vector index starts automatically with hati init.

Register a Semantic Trigger

Create a trigger that fires when any agent discusses sensitive financial data.

Python

from hatidata_agent import HatiDataAgent

hati = HatiDataAgent(host="localhost", port=5439, agent_id="trigger-admin")

# Register a trigger for sensitive financial discussions
hati.execute("""
    SELECT register_trigger(
        'financial-data-alert',
        'Discussion of revenue numbers, financial projections, or earnings data',
        0.75,
        'webhook',
        'https://your-webhook.example.com/alerts'
    )
""")

print("Trigger registered: financial-data-alert")
print("  Concept: financial projections and earnings")
print("  Threshold: 0.75 cosine similarity")
print("  Action: webhook POST")

Expected Output

Trigger registered: financial-data-alert
  Concept: financial projections and earnings
  Threshold: 0.75 cosine similarity
  Action: webhook POST

Note: The threshold (0.75) controls sensitivity. Lower values catch more mentions but may produce false positives.

Set Up a Webhook Receiver

Create a simple webhook receiver to handle trigger notifications with HMAC verification.

Python

# webhook_receiver.py
from flask import Flask, request, jsonify
import hmac
import hashlib

app = Flask(__name__)
WEBHOOK_SECRET = "your-webhook-secret"

@app.route("/alerts", methods=["POST"])
def handle_trigger():
    # Verify HMAC-SHA256 signature
    signature = request.headers.get("X-HatiData-Signature")
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        request.data,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature or "", expected):
        return jsonify({"error": "Invalid signature"}), 401

    payload = request.json
    print(f"Trigger fired: {payload['trigger_name']}")
    print(f"  Agent: {payload['agent_id']}")
    print(f"  Similarity: {payload['similarity_score']}")
    print(f"  Content: {payload['matched_content'][:100]}")
    return jsonify({"status": "received"}), 200

if __name__ == "__main__":
    app.run(port=9090)

Expected Output

* Running on http://127.0.0.1:9090

Note: Always verify the HMAC signature in production to ensure the webhook came from HatiData.

Run CrewAI Agents and Observe Triggers

Run a CrewAI crew and watch triggers fire when agents discuss financial topics.

Python

from crewai import Agent, Task, Crew
from hatidata_agent import HatiDataAgent

hati = HatiDataAgent(host="localhost", port=5439, agent_id="crew-analyst")

analyst = Agent(
    role="Financial Analyst",
    goal="Analyze quarterly revenue and provide forecasts",
    backstory="You are an expert financial analyst.",
)

task = Task(
    description="Analyze Q3 revenue: total was $4.2M, up 28% YoY. Project Q4 earnings.",
    agent=analyst,
)

# Store the analysis (this will trigger the financial-data-alert)
hati.execute("""
    SELECT store_memory(
        'Q3 revenue hit $4.2M (+28% YoY). Projecting Q4 at $5.1M based on pipeline.',
        'financial-analysis'
    )
""")

print("Memory stored — check webhook receiver for trigger notification")

Expected Output

Memory stored — check webhook receiver for trigger notification

# In the webhook receiver terminal:
Trigger fired: financial-data-alert
  Agent: crew-analyst
  Similarity: 0.89
  Content: Q3 revenue hit $4.2M (+28% YoY). Projecting Q4 at $5.1M based on pipeline.

Test Triggers Manually

Use the test_trigger tool to verify your triggers work without running the full crew.

Python

# Test trigger with sample text
result = hati.query("""
    SELECT test_trigger(
        'financial-data-alert',
        'We need to discuss the upcoming earnings report and revenue projections'
    )
""")

print(f"Trigger match: {result[0]['matched']}")
print(f"Similarity: {result[0]['similarity']}")

# List all registered triggers
triggers = hati.query("""
    SELECT trigger_name, concept, threshold, action_type
    FROM _hatidata_triggers.registry
    ORDER BY created_at DESC
""")

print(f"\nRegistered triggers: {len(triggers)}")
for t in triggers:
    print(f"  {t['trigger_name']}: threshold={t['threshold']}, action={t['action_type']}")

Expected Output

Trigger match: true
Similarity: 0.82

Registered triggers: 1
  financial-data-alert: threshold=0.75, action=webhook

Note: test_trigger() runs the full evaluation pipeline without actually firing the action — useful for tuning thresholds.

Related Use Case

Security

Cybersecurity Threat Hunting

Threat Hunting with Semantic Intelligence

Ready to build?

Install HatiData locally and start building with CrewAI in minutes.

Join Waitlist