Superagent LogoSuperagent

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 with uv 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 configured httpx.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

KeyTypeDescription
result.decision.statusLiteral["pass", "block"]Machine verdict that determines whether the command is allowed.
result.decision.violation_typeslist[str] | NoneCategories that explain the reason for blocking a command.
result.decision.cwe_codeslist[str] | NoneCWE identifiers attached to the detected violation.
result.rejectedboolConvenience flag that mirrors result.decision.status != "pass".
result.reasoningstrHuman-readable explanation accompanying the decision.