ApplyGuardrailScope Class

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")

Initialize the guardrail scope.

Constructor

ApplyGuardrailScope(details: GuardrailDetails, agent_details: AgentDetails, request: Request | None = None, user_details: UserDetails | None = None, span_details: SpanDetails | None = None)

Parameters

Name	Description
details Required	Guardrail evaluation details.
agent_details Required	Agent identity details.
request	Optional request context. Default value: None
user_details	Optional human user details. Default value: None
span_details	Optional span configuration. Default value: None

Methods

record_content_input	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.
record_content_output	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.
record_decision	Update the guardrail decision on the span. Use this to update the decision mid-flight if the initial decision changes after evaluation completes.
record_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.
start	Create and start a new scope for guardrail evaluation tracing.

record_content_input

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.

record_content_input(input_value: str | list[str] | InputMessages) -> None

Parameters

Name	Description
input_value Required	The input content as a string or InputMessagesParam.

record_content_output

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.

record_content_output(output_value: str) -> None

Parameters

Name	Description
output_value Required	The output content string.

record_decision

Update the guardrail decision on the span.

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

record_decision(decision_type: str, reason: str | None = None) -> None

Parameters

Name	Description
decision_type Required	The decision type (use GuardrailDecisionType constants).
reason	Optional human-readable reason for the decision. Default value: None

record_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.

record_finding(finding: GuardrailFinding) -> None

Parameters

Name	Description
finding Required	The security finding to record.

start

Create and start a new scope for guardrail evaluation tracing.

static start(details: GuardrailDetails, agent_details: AgentDetails, request: Request | None = None, user_details: UserDetails | None = None, span_details: SpanDetails | None = None) -> ApplyGuardrailScope

Parameters

Name	Description
details Required	Guardrail evaluation details (required).
agent_details Required	Agent identity details (required).
request	Optional request context (conversation ID, channel, content). Default value: None
user_details	Optional human user details. Default value: None
span_details	Optional span configuration (parent context, timing, kind). Default value: None

Returns

Type	Description
	A new ApplyGuardrailScope instance.