Skip to content

Same agent Smaller bill. The tools and infrastructure to get more work from your AI. Fewer tokens. Less compute. Lower cost.

feat(python): add agent threat event helper (#1204)

Ritwij Aryan Parmare0b019987a14
diff --git a/sdk/python/src/openlit/semcov/__init__.py b/sdk/python/src/openlit/semcov/__init__.py
index b58e7c58..eef0a177 100644
--- a/sdk/python/src/openlit/semcov/__init__.py
+++ b/sdk/python/src/openlit/semcov/__init__.py
@@ -737,6 +737,12 @@ class SemanticConvention:
GEN_AI_AGENT_FINISH_OUTPUT = "gen_ai.agent.finish.output"
GEN_AI_AGENT_FINISH_LOG = "gen_ai.agent.finish.log"
+ # Agent Threat Detection Events
+ GEN_AI_AGENT_THREAT_DETECTED = "gen_ai.agent.threat_detected"
+ GEN_AI_AGENT_THREAT_RULE_ID = "gen_ai.agent.threat.rule_id"
+ GEN_AI_AGENT_THREAT_SEVERITY = "gen_ai.agent.threat.severity"
+ GEN_AI_AGENT_THREAT_CLASS = "gen_ai.agent.threat.threat_class"
+
GEN_AI_AGENT_TYPE_BROWSER = "browser"
# Crawl4AI Specific Attributes (0.7.x Support)
diff --git a/sdk/python/src/openlit/threat.py b/sdk/python/src/openlit/threat.py
new file mode 100644
index 00000000..21b63022
--- /dev/null
+++ b/sdk/python/src/openlit/threat.py
@@ -0,0 +1,58 @@
+"""
+Threat telemetry helpers for AI applications.
+"""
+
+from opentelemetry import trace
+
+from openlit.semcov import SemanticConvention
+
+_VALID_SEVERITIES = {"low", "medium", "high", "critical"}
+_CORE_ATTRIBUTE_KEYS = {
+ SemanticConvention.GEN_AI_AGENT_THREAT_RULE_ID,
+ SemanticConvention.GEN_AI_AGENT_THREAT_SEVERITY,
+ SemanticConvention.GEN_AI_AGENT_THREAT_CLASS,
+}
+
+
+def record_threat_detected(
+ rule_id: str,
+ severity: str,
+ threat_class: str,
+ *,
+ span=None,
+ **attributes,
+) -> bool:
+ """
+ Add a `gen_ai.agent.threat_detected` event to the current span.
+
+ Returns `True` when an event is emitted and `False` when no recording span is
+ available. This keeps guardrail and scanner integrations safe to call from
+ request paths where tracing may be disabled.
+ """
+ if not rule_id:
+ raise ValueError("rule_id is required")
+ if severity not in _VALID_SEVERITIES:
+ raise ValueError("severity must be one of: critical, high, medium, low")
+ if not threat_class:
+ raise ValueError("threat_class is required")
+
+ target_span = span or trace.get_current_span()
+ if not target_span or not target_span.is_recording():
+ return False
+
+ event_attributes = {
+ key: value
+ for key, value in attributes.items()
+ if isinstance(key, str)
+ and value is not None
+ and key not in _CORE_ATTRIBUTE_KEYS
+ }
+ event_attributes[SemanticConvention.GEN_AI_AGENT_THREAT_RULE_ID] = rule_id
+ event_attributes[SemanticConvention.GEN_AI_AGENT_THREAT_SEVERITY] = severity
+ event_attributes[SemanticConvention.GEN_AI_AGENT_THREAT_CLASS] = threat_class
+
+ target_span.add_event(
+ SemanticConvention.GEN_AI_AGENT_THREAT_DETECTED,
+ attributes=event_attributes,
+ )
+ return True
diff --git a/sdk/python/tests/test_threat_event.py b/sdk/python/tests/test_threat_event.py
new file mode 100644
index 00000000..b6ac601e
--- /dev/null
+++ b/sdk/python/tests/test_threat_event.py
@@ -0,0 +1,120 @@
+# pylint: disable=missing-function-docstring
+"""
+Tests for the OpenTelemetry-native agent threat detection event helper.
+"""
+
+from unittest.mock import Mock, patch
+
+import pytest
+
+from openlit.threat import record_threat_detected
+from openlit.semcov import SemanticConvention
+
+
+def test_record_threat_detected_adds_standard_event_to_explicit_span():
+ span = Mock()
+ span.is_recording.return_value = True
+
+ emitted = record_threat_detected(
+ "openlit.guard.prompt_injection.impersonation",
+ "high",
+ "prompt_injection",
+ span=span,
+ detector="openlit.guard",
+ confidence=0.94,
+ ignored=None,
+ )
+
+ assert emitted is True
+ span.add_event.assert_called_once_with(
+ SemanticConvention.GEN_AI_AGENT_THREAT_DETECTED,
+ attributes={
+ SemanticConvention.GEN_AI_AGENT_THREAT_RULE_ID: (
+ "openlit.guard.prompt_injection.impersonation"
+ ),
+ SemanticConvention.GEN_AI_AGENT_THREAT_SEVERITY: "high",
+ SemanticConvention.GEN_AI_AGENT_THREAT_CLASS: "prompt_injection",
+ "detector": "openlit.guard",
+ "confidence": 0.94,
+ },
+ )
+
+
+def test_record_threat_detected_uses_current_span_when_span_not_provided():
+ span = Mock()
+ span.is_recording.return_value = True
+
+ with patch("opentelemetry.trace.get_current_span", return_value=span):
+ emitted = record_threat_detected(
+ "atr-2026-00001",
+ "critical",
+ "exfiltration",
+ )
+
+ assert emitted is True
+ assert (
+ span.add_event.call_args[0][0]
+ == SemanticConvention.GEN_AI_AGENT_THREAT_DETECTED
+ )
+
+
+def test_record_threat_detected_preserves_validated_core_attributes():
+ span = Mock()
+ span.is_recording.return_value = True
+
+ emitted = record_threat_detected(
+ "rule-1",
+ "high",
+ "jailbreak",
+ span=span,
+ detector="openlit.guard",
+ **{
+ SemanticConvention.GEN_AI_AGENT_THREAT_RULE_ID: "rule-2",
+ SemanticConvention.GEN_AI_AGENT_THREAT_SEVERITY: "low",
+ SemanticConvention.GEN_AI_AGENT_THREAT_CLASS: "prompt_injection",
+ },
+ )
+
+ assert emitted is True
+ span.add_event.assert_called_once_with(
+ SemanticConvention.GEN_AI_AGENT_THREAT_DETECTED,
+ attributes={
+ SemanticConvention.GEN_AI_AGENT_THREAT_RULE_ID: "rule-1",
+ SemanticConvention.GEN_AI_AGENT_THREAT_SEVERITY: "high",
+ SemanticConvention.GEN_AI_AGENT_THREAT_CLASS: "jailbreak",
+ "detector": "openlit.guard",
+ },
+ )
+
+
+def test_record_threat_detected_returns_false_without_recording_span():
+ span = Mock()
+ span.is_recording.return_value = False
+
+ emitted = record_threat_detected(
+ "rule-1",
+ "medium",
+ "jailbreak",
+ span=span,
+ )
+
+ assert emitted is False
+ span.add_event.assert_not_called()
+
+
[email protected]("severity", ["", "warn", "severe", "HIGH"])
+def test_record_threat_detected_rejects_invalid_severity(severity):
+ with pytest.raises(ValueError, match="severity must be one of"):
+ record_threat_detected("rule-1", severity, "prompt_injection")
+
+
+ ("rule_id", "threat_class", "message"),
+ [
+ ("", "prompt_injection", "rule_id is required"),
+ ("rule-1", "", "threat_class is required"),
+ ],
+)
+def test_record_threat_detected_requires_core_attributes(rule_id, threat_class, message):
+ with pytest.raises(ValueError, match=message):
+ record_threat_detected(rule_id, "low", threat_class)