microsoft.opentelemetry.a365.core.apply_guardrail_scope module

OpenTelemetry tracing scope for guardrail (security guardian) evaluations.

class microsoft.opentelemetry.a365.core.apply_guardrail_scope.ApplyGuardrailScope(details, agent_details, request=None, user_details=None, span_details=None)

Bases: OpenTelemetryScope

Provides OpenTelemetry tracing scope for security guardrail evaluations.

Guardian spans SHOULD be children of the operation span they are protecting (e.g., inference or execute_tool spans). Multiple guardian spans MAY exist under a single operation span if multiple guardians are chained.

Example usage:

from microsoft.opentelemetry.a365.core import (
    ApplyGuardrailScope, GuardrailDetails, AgentDetails,
    GuardrailDecisionType, GuardrailTargetType, GuardrailRiskSeverity,
    GuardrailFinding,
)

details = GuardrailDetails(
    target_type=GuardrailTargetType.LLM_INPUT,
    decision_type=GuardrailDecisionType.ALLOW,
    guardian_name="Azure Content Safety",
)

with ApplyGuardrailScope.start(details, agent_details) as scope:
    # ... run guardrail evaluation ...
    scope.record_finding(GuardrailFinding(
        risk_category="hate_speech",
        risk_severity=GuardrailRiskSeverity.HIGH,
        risk_score=0.95,
    ))
    scope.record_decision(GuardrailDecisionType.DENY, "Blocked by policy")

static start(details, agent_details, request=None, user_details=None, span_details=None)

Create and start a new scope for guardrail evaluation tracing.

Parameters:

• details (GuardrailDetails) – Guardrail evaluation details (required).

• agent_details (AgentDetails) – Agent identity details (required).

• request (Request | None) – Optional request context (conversation ID, channel, content).

• user_details (UserDetails | None) – Optional human user details.

• span_details (SpanDetails | None) – Optional span configuration (parent context, timing, kind).

Return type:

ApplyGuardrailScope

Returns:

A new ApplyGuardrailScope instance.

record_decision(decision_type, reason=None)

Update the guardrail decision on the span.

Use this to update the decision mid-flight if the initial decision changes after evaluation completes.

Parameters:

• decision_type (str) – The decision type (use GuardrailDecisionType constants).

• reason (str | None) – Optional human-readable reason for the decision.

Return type:

None

record_content_output(output_value)

Record the sanitized/modified output content (opt-in).

This is an opt-in field for recording output content after guardrail processing. Only set this when content capture is explicitly enabled.

Parameters:

output_value (str) – The output content string.

Return type:

None

record_content_input(input_value)

Record the input content being evaluated (opt-in).

This is an opt-in field for recording input content sent to the guardrail. Only set this when content capture is explicitly enabled.

Accepts plain strings or structured InputMessages containers. Structured messages are normalized and serialized to a JSON string before being set as an attribute.

Parameters:

input_value (Union[str, list[str], InputMessages]) – The input content as a string or InputMessagesParam.

Return type:

None

record_finding(finding)

Record a security finding as a span event.

Each call adds a separate microsoft.security.finding event to the span. Multiple findings can be recorded for a single guardrail evaluation.

Parameters:

finding (GuardrailFinding) – The security finding to record.

Return type:

None