Same agent Smaller bill. The tools and infrastructure to get more work from your AI. Fewer tokens. Less compute. Lower cost.
TypeScript agent-harnessagent-harness-engineeringai-engineeringai-observabilityamd-gpuclaude-codeclickhousecodexcoding-agentcoding-agentscursorgenaigpu-monitoringllm-observabilityllmopsnvidia-smiobservabilityopen-sourceopenaiopentelemetry
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__.pyindex 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.pynew file mode 100644index 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 Truediff --git a/sdk/python/tests/test_threat_event.py b/sdk/python/tests/test_threat_event.pynew file mode 100644index 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)