Skip to main content

​
Overview

Use respan-exporter-superagent to wrap the Superagent Python SDK (safety-agent). Each call to guard, redact, scan, or test is executed as usual and a log is exported to Respan Traces so you can observe safety checks in your Respan dashboard.

​
Quickstart

​
Step 1: Get a Respan API key

Create an API key in your Respan dashboard.

​
Step 2: Install packages

pip install safety-agent respan-exporter-superagent

​
Step 3: Set environment variables

Create a .env or export environment variables:
.env
# Required for Respan export
RESPAN_API_KEY=your-respan-api-key

# Optional (default: Respan tracing ingest endpoint)
RESPAN_ENDPOINT=https://api.respan.ai/api/v1/traces/ingest

# Required by safety-agent for usage tracking
SUPERAGENT_API_KEY=your-superagent-api-key

​
Step 4: Create a client and call Superagent

Use create_client from respan_exporter_superagent instead of safety_agent. The client supports the same methods as the Superagent SDK; each call is logged to Respan when respan_params is provided (or when you rely on defaults). 
import os
import asyncio
from respan_exporter_superagent import create_client


async def main() -> None:
    client = create_client(
        api_key=os.getenv("RESPAN_API_KEY"),
        endpoint=os.getenv("RESPAN_ENDPOINT"),  # optional
    )

    result = await client.guard(
        input="hello",
        respan_params={
            "span_workflow_name": "wf",
            "span_name": "sp",
            "customer_identifier": "user-123",
        },
    )
    print(result)


if __name__ == "__main__":
    asyncio.run(main())

​
Step 5: View your trace

Open the Traces page in your Respan dashboard. Logs appear as tool spans with integration: superagent and method: guard (or redact, scan, test) in metadata.

​
Supported methods

The Respan Superagent client wraps the same methods as the Superagent SDK:
MethodDescription
guardRun guard model on input (e.g. content safety).
redactRedact PII/sensitive data.
scanScan content.
testRun tests.
Pass Superagent-specific arguments (e.g. model, text, repo) as keyword arguments; pass respan_params to control how the call is logged to Respan.

​
Respan parameters

Use respan_params on any method to set span and trace fields in Respan:
  • span_workflow_name – Workflow name (default: "superagent").
  • span_name – Span name (default: "superagent.<method>").
  • customer_identifier – User or tenant ID for filtering.
  • disable_log – Set to True to skip sending this call to Respan.
  • log_type – Log type (default: "tool").
  • trace_unique_id, trace_name, span_unique_id, span_parent_id, session_identifier, metadata – Optional trace/span and metadata fields.
Example: 
result = await client.redact(
    input="My email is john@example.com",
    model="openai/gpt-4o-mini",
    respan_params={
        "span_workflow_name": "pii_redaction",
        "span_name": "redact_step",
        "customer_identifier": "user-456",
    },
)

​
Disable logging for a call

To call Superagent without exporting to Respan for that call: 
result = await client.guard(
    input="sensitive input",
    respan_params={"disable_log": True},
)

​
Using an existing Superagent client

You can wrap an existing safety_agent client so only Respan export is added: 
from safety_agent import create_client as superagent_create_client
from respan_exporter_superagent import create_client

superagent_client = superagent_create_client()
client = create_client(
    api_key=os.getenv("RESPAN_API_KEY"),
    client=superagent_client,
)

result = await client.guard(input="hello", respan_params={"span_name": "my_guard"})