Superagent LogoSuperagent

TypeScript SDK

Lightweight TypeScript client for implementing Superagent in your app

Superagent Guard TypeScript SDK

A lightweight client for calling the Superagent Guard endpoint from TypeScript or JavaScript projects.

Installation

npm install superagent-ai
# or
pnpm add superagent-ai
# or
yarn add superagent-ai

Usage

import { createGuard } from "superagent-ai";

const guard = createGuard({
  apiBaseUrl: "https://app.superagent.sh/api/guard",
  apiKey: process.env.SUPERAGENT_API_KEY!,
});

const command = "Write a benign hello world script";

const { decision, reasoning } = await guard(command, {
  onBlock: (reason) => {
    console.warn("Guard blocked command:", reason);
  },
  onPass: () => {
    console.log("Guard approved command, continue!");
  },
});

if (decision.status === "block") {
  console.warn("Violations:", decision.violation_types ?? []);
  console.warn("CWE codes:", decision.cwe_codes ?? []);
  // handle rejection logic
} else {
  // proceed with the approved command
}

Options

  • apiBaseUrl – fully qualified URL for your Guard endpoint.
  • apiKey – API key provisioned in Superagent.
  • fetch – optional custom fetch implementation (defaults to global fetch).
  • timeoutMs – optional timeout for the outbound request.

The guard response surfaces the parsed decision alongside human-readable reasoning, making it straightforward to plug into custom workflows or audit logs. The decision object exposes the machine-readable security outcome: status (either pass or block), plus optional violation_types and cwe_codes arrays that classify why a command was blocked.

Response fields

KeyTypeDescription
decision.status"pass" | "block"Machine verdict that drives allow/block handling.
decision.violation_typesstring[] | undefinedCategories that describe why the guard blocked a command.
decision.cwe_codesstring[] | undefinedCWE identifiers associated with the detected violation.
rejectedbooleanConvenience flag that mirrors decision.status !== "pass".
reasoningstringHuman-readable explanation accompanying the decision.