Trace Guardrails AI validations

Trace a Guardrails AI validation in Future AGI, including the validator name and result. The example below validates a fixed string locally; it does not call a model or require a model-provider key.

Install

Use Python 3.10–3.13, as required by traceAI-guardrails 0.2.0.

pip install traceAI-guardrails==0.2.0

Set environment variables

Set your Future AGI API keys in the terminal that runs the application:

export FI_API_KEY="your-futureagi-api-key"
export FI_SECRET_KEY="your-futureagi-secret-key"

Configure tracing

Register the provider and enable instrumentation before creating the guard:

from fi_instrumentation import register, TraceConfig
from fi_instrumentation.fi_types import ProjectType
from traceai_guardrails import GuardrailsInstrumentor

trace_provider = register(
    project_type=ProjectType.OBSERVE,
    project_name="guardrails_project",
)

GuardrailsInstrumentor().instrument(
    tracer_provider=trace_provider,
    config=TraceConfig(hide_inputs=True, hide_outputs=True),
)

The instrumentor can capture validation inputs, outputs and validator metadata. This example hides standard input and output attributes. These switches are not a filter for arbitrary validator metadata or exception text: do not put sensitive data in custom metadata or error messages. See Mask span attributes for the available controls.

Run a validation

Add this code to the same script. It uses Guardrails’ custom validator API to require exactly two words:

from guardrails import Guard
from guardrails.validators import FailResult, PassResult, Validator, register_validator


@register_validator(name="two-words", data_type="string")
class TwoWords(Validator):
    def _validate(self, value, metadata):
        if len(value.split()) == 2:
            return PassResult()
        return FailResult(error_message="Expected exactly two words.")


guard = Guard().use(TwoWords(on_fail="exception"))

try:
    result = guard.validate("Hello world")
    print(result.validation_passed)
finally:
    trace_provider.force_flush()

Open Observe, select guardrails_project, and inspect the validation spans. The instrumentor wraps Guardrails’ runner and post-validation processing; this example exercises a validator rather than an empty Guard(). Standard input and output content remains hidden by the configuration above.