Python SDK
Async Python client for implementing Superagent into your apps
Superagent Guard Python SDK
Python client for sending commands to the Superagent Guard endpoint.
Installation
uv add superagent-ai
Tip:
uv add
pins the dependency in your project; run examples withuv run
if you aren't using a dedicated virtual environment.
Quick start
import asyncio
from superagent_ai import create_guard
async def main() -> None:
guard = create_guard(
api_base_url="https://app.superagent.sh/api/guard",
api_key="sk-...",
)
result = await guard(
"Generate a friendly greeting",
on_block=lambda reason: print("Guard blocked:", reason),
on_pass=lambda: print("Guard passed"),
)
if result.decision.status == "block":
print("Violations:", result.decision.violation_types or [])
print("CWE codes:", result.decision.cwe_codes or [])
print("Rejected with:", result.reasoning)
else:
print("Approved", result.decision.status)
await guard.aclose()
asyncio.run(main())
Options
api_base_url
– fully qualified URL for your Guard endpoint.api_key
– API key provisioned in Superagent.timeout
– optional request timeout (defaults to 10 seconds).client
– optionally provide your own configuredhttpx.AsyncClient
.
The returned GuardResult
includes the parsed decision and explanatory reasoning for straightforward policy enforcement. The decision
object contains the machine-readable verdict via status
("pass"
or "block"
) along with optional violation_types
and cwe_codes
lists when the guard rejects a command.
Response fields
Key | Type | Description |
---|---|---|
result.decision.status | Literal["pass", "block"] | Machine verdict that determines whether the command is allowed. |
result.decision.violation_types | list[str] | None | Categories that explain the reason for blocking a command. |
result.decision.cwe_codes | list[str] | None | CWE identifiers attached to the detected violation. |
result.rejected | bool | Convenience flag that mirrors result.decision.status != "pass" . |
result.reasoning | str | Human-readable explanation accompanying the decision. |