Superagent | Respan Docs

Overview

respan-instrumentation-superagent is an instrumentation plugin that captures calls from the Superagent safety-agent SDK and sends them to Respan through the unified OpenTelemetry pipeline.

It monkey-patches safety_agent.client.SafetyClient methods and emits canonical Respan spans for guard, redact, scan, and future compatible Superagent methods.

$ pip install respan-ai respan-instrumentation-superagent safety-agent

Version: 0.1.0 | Python: >=3.11, <3.14

Dependencies

Package	Version
`respan-tracing`	^2.16.1
`respan-sdk`	>=2.5.0
`safety-agent`	>=0.1.5

Quick start

1 from respan import Respan
2 from respan_instrumentation_superagent import SuperagentInstrumentor
3 from safety_agent import create_client
4 
5 respan = Respan(
6     api_key="your-respan-api-key",
7     instrumentations=[SuperagentInstrumentor()],
8 )
9 
10 client = create_client()
11 result = await client.guard(input="Check this content for safety.")
12 print(result.classification)
13 respan.flush()

Public API

SuperagentInstrumentor

The main instrumentor class. Implements the Instrumentation protocol.

1 from respan_instrumentation_superagent import SuperagentInstrumentor

Attribute/Method	Type	Description
`name`	`str`	`"superagent"` — unique plugin identifier.
`activate()`	`() -> None`	Patches compatible `SafetyClient` methods.
`deactivate()`	`() -> None`	Restores the original `SafetyClient` methods when the last active instrumentor is deactivated.

Constructor

1 SuperagentInstrumentor(methods=("guard", "redact", "scan", "test"))

Parameter	Type	Default	Description
`methods`	`tuple[str, ...] \| None`	`None`	Optional method allowlist. Defaults to all supported Superagent methods. Missing methods are skipped for SDK-version compatibility.

Captured operations

Superagent Method	Log Type	Description
`guard`	`guardrail`	Prompt-injection and safety classification.
`redact`	`tool`	PII or sensitive-content redaction.
`scan`	`tool`	Repository safety analysis.
`test`	`tool`	Future-compatible Superagent test method when present in the installed SDK.

Span attributes

All emitted spans include:

Attribute	Description
`respan.entity.log_type`	`guardrail` for `guard`; `tool` for the other operations.
`traceloop.entity.name`	Operation name, for example `superagent.guard`.
`traceloop.entity.path`	Operation path used for parent-child trace nesting.
`traceloop.entity.input`	JSON-serialized method arguments.
`traceloop.entity.output`	JSON-serialized result or error.
`respan.metadata.integration`	Always `superagent`.
`respan.metadata.superagent_method`	Captured method name.
`respan.metadata.superagent_model`	Model argument when provided.

guard() spans additionally include:

Attribute	Description
`respan.metadata.guardrail_name`	`superagent.guard`.
`respan.metadata.triggered`	Whether the guard classification was `block`.
`respan.metadata.superagent_classification`	`pass` or `block`.

With propagated attributes

Use propagate_attributes() to attach per-request metadata to all Superagent spans:

1 from respan import Respan, propagate_attributes
2 from respan_instrumentation_superagent import SuperagentInstrumentor
3 from safety_agent import create_client
4 
5 respan = Respan(instrumentations=[SuperagentInstrumentor()])
6 client = create_client()
7 
8 async def handle_user_request(user_id: str, message: str):
9     with propagate_attributes(
10         customer_identifier=user_id,
11         thread_identifier="thread-123",
12         metadata={"surface": "chat-input"},
13     ):
14         result = await client.guard(input=message)
15         return result.classification

With decorators

Combine Superagent instrumentation with decorators when you want application-level structure around safety checks:

1 from respan import Respan, task, workflow
2 from respan_instrumentation_superagent import SuperagentInstrumentor
3 from safety_agent import create_client
4 
5 respan = Respan(instrumentations=[SuperagentInstrumentor()])
6 client = create_client()
7 
8 @task(name="guard_user_input")
9 async def guard_user_input(message: str) -> str:
10     result = await client.guard(input=message)
11     return result.classification
12 
13 @workflow(name="chat_safety_pipeline")
14 async def chat_safety_pipeline(message: str) -> str:
15     return await guard_user_input(message)

Architecture

Superagent safety-agent SDK
  │
  ├─ SafetyClient.guard()   ──→  SuperagentInstrumentor wrapper ──→ build_readable_span() ──→ inject_span()
  │                                                                                                 │
  ├─ SafetyClient.redact()  ──→  SuperagentInstrumentor wrapper ──→ build_readable_span() ──→ inject_span()
  │                                                                                                 │
  ├─ SafetyClient.scan()    ──→  SuperagentInstrumentor wrapper ──→ build_readable_span() ──→ inject_span()
  │                                                                                                 │
  └─ ...                    ──→  ...                           ──→ ...                 ──→ ...
                                                                                                    │
                                                                                                    ▼
                                                                                         OTEL Processor Chain
                                                                                                    │
                                                                                                    ▼
                                                                                         RespanSpanExporter
                                                                                                    │
                                                                                                    ▼
                                                                                           POST /v2/traces

Internal modules

These are implementation details, not part of the public API:

Module	Description
`_instrumentation.py`	`SuperagentInstrumentor`, method patching, and restore logic.
`_span_emitter.py`	Canonical Respan span attribute mapping and span injection.
`_serialization.py`	JSON-safe method input/output serialization helpers.
`_constants.py`	Superagent-specific method names and metadata keys.