> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# Guardrails (tracing)

> Trace Guardrails AI validation workflows with Respan — auto-instrumented spans, gateway routing, and full observability.

[Guardrails AI](https://www.guardrailsai.com/) is a framework for adding structural, type, and quality guarantees to LLM outputs. It validates, corrects, and structures LLM responses to ensure they meet your requirements. Respan gives you full observability over every guard validation, re-ask loop, validator execution, and LLM call — and gateway routing through the OpenAI-compatible Respan endpoint.

#### Set up Respan

Create an account at [platform.respan.ai](https://platform.respan.ai) and grab an [API key](https://platform.respan.ai/platform/gateway/api-keys).

Run `npx @respan/cli setup` to set up with your coding agent.

#### Use Respan Gateway

See [Guardrails AI gateway setup](/docs/gateway/guardrails) to route this integration through the Respan gateway.

#### Example projects

* [Example projects root](https://github.com/respanai/respan-example-projects)

## Setup

#### Install packages

```bash
pip install respan-ai respan-instrumentation-guardrails guardrails-ai
```

#### Set environment variables

```bash
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
```

`OPENAI_API_KEY` is used for LLM requests. `RESPAN_API_KEY` is used to export traces to Respan.

#### Initialize and run

```python
import os
from typing import Literal

from guardrails import Guard
from pydantic import BaseModel, Field
from respan import Respan
from respan_instrumentation_guardrails import GuardrailsInstrumentor

class SupportReply(BaseModel):
    answer: str = Field(description="Customer-facing answer")
    priority: Literal["low", "medium", "high"] = Field(description="Ticket priority")

respan = Respan(
    api_key=os.environ["RESPAN_API_KEY"],
    instrumentations=[GuardrailsInstrumentor()],
)

guard = Guard.for_pydantic(output_class=SupportReply)

result = guard(
    model="gpt-4o-mini",
    messages=[{
        "role": "user",
        "content": "Return JSON with answer and priority for a delayed shipment."
    }],
)
print(result.validated_output)
```

#### View your trace

Open the [Traces page](https://platform.respan.ai/platform/traces) to see your Guardrails workflow with validation passes, re-ask loops, and LLM calls.

## Configuration

| Parameter             | Type           | Default | Description                                                            |
| --------------------- | -------------- | ------- | ---------------------------------------------------------------------- |
| `api_key`             | `str \| None`  | `None`  | Falls back to `RESPAN_API_KEY` env var.                                |
| `base_url`            | `str \| None`  | `None`  | Falls back to `RESPAN_BASE_URL` env var.                               |
| `instrumentations`    | `list`         | `[]`    | Plugin instrumentations to activate (e.g. `GuardrailsInstrumentor()`). |
| `customer_identifier` | `str \| None`  | `None`  | Default customer identifier for all spans.                             |
| `metadata`            | `dict \| None` | `None`  | Default metadata attached to all spans.                                |
| `environment`         | `str \| None`  | `None`  | Environment tag (e.g. `"production"`).                                 |

## Attributes

### In Respan()

Set defaults at initialization — these apply to all spans.

```python
from respan import Respan
from respan_instrumentation_guardrails import GuardrailsInstrumentor

respan = Respan(
    instrumentations=[GuardrailsInstrumentor()],
    customer_identifier="user_123",
    metadata={"service": "guardrails-api", "version": "1.0.0"},
)
```

### With propagate_attributes

Override per-request using a context scope.

```python
from respan import Respan, propagate_attributes
from respan_instrumentation_guardrails import GuardrailsInstrumentor

respan = Respan(instrumentations=[GuardrailsInstrumentor()])

def handle_request(user_id: str, prompt: str):
    with propagate_attributes(
        customer_identifier=user_id,
        thread_identifier="conv_abc_123",
        metadata={"plan": "pro"},
    ):
        result = guard(model="gpt-4o-mini", messages=[{"role": "user", "content": prompt}])
        print(result.validated_output)
```

| Attribute             | Type   | Description                                           |
| --------------------- | ------ | ----------------------------------------------------- |
| `customer_identifier` | `str`  | Identifies the end user in Respan analytics.          |
| `thread_identifier`   | `str`  | Groups related messages into a conversation.          |
| `metadata`            | `dict` | Custom key-value pairs. Merged with default metadata. |