@agentguardorg/node

Official Node.js / TypeScript SDK for AgentGuard — the AI action firewall that keeps your agents safe.

Install

npm install @agentguardorg/node
# or
pnpm add @agentguardorg/node
# or
yarn add @agentguardorg/node

Requirements: Node.js 18 or later (uses native fetch).

Quick Start

import { AgentGuard } from "@agentguardorg/node";

const guard = new AgentGuard({ apiKey: "ag_live_YOUR_KEY_HERE" });

Then, before your agent executes any action:

const result = await guard.check({
  action: "send_email",
  payload: { to: "[email protected]", body: "Hello!" },
});

if (result.decision === "block") {
  throw new Error(`Action blocked: ${result.reason}`);
}

// proceed with the action

Constructor Options

new AgentGuard({
  apiKey: string;          // required — from your AgentGuard dashboard
  baseUrl?: string;        // default: https://agentguard.dev/api
                           // also read from AGENTGUARD_BASE_URL env var
  timeoutMs?: number;      // default: 5000
})

The baseUrl is resolved in this order:

1. options.baseUrl passed to the constructor
2. AGENTGUARD_BASE_URL environment variable
3. https://agentguard.dev/api (production default)

guard.check() Reference

const result = await guard.check({
  action: string;                        // required — name of the action
  payload: Record<string, unknown>;      // required — data the agent is acting on
  agentId?: string;                      // which agent is acting (improves logging)
  appUserId?: string;                    // end user ID (enables cross-user detection)
  appName?: string;                      // identifies your app in the dashboard
  riskContext?: Record<string, unknown>; // extra metadata for risk scoring
});

Return value

{
  decision: "allow" | "block" | "review";
  riskLevel: "low" | "medium" | "high" | "critical";
  reason: string;
  logId: number | null;
  promptInjectionDetected: boolean;
}

Handling Each Decision

const result = await guard.check({ action, payload });

switch (result.decision) {
  case "allow":
    // Safe to proceed. Execute the action.
    await executeAction(action, payload);
    break;

  case "review":
    // High-risk but not definitively malicious.
    // Queue for human review or notify your security team.
    await queueForReview(action, payload, result.reason);
    break;

  case "block":
    // Policy violation or detected threat. Do NOT proceed.
    throw new Error(`Blocked (${result.riskLevel}): ${result.reason}`);
}

Error Handling

The SDK throws typed errors so you can handle failures precisely:

import {
  AgentGuard,
  AgentGuardAuthError,
  AgentGuardNetworkError,
  AgentGuardServerError,
} from "@agentguardorg/node";

try {
  const result = await guard.check({ action, payload });
} catch (err) {
  if (err instanceof AgentGuardAuthError) {
    // Invalid or expired API key — check your dashboard
    console.error("Auth error:", err.message);
  } else if (err instanceof AgentGuardNetworkError) {
    // Connectivity issue — the SDK already retried once
    // Fall back gracefully (allow or queue for later)
    console.error("Network error:", err.message);
  } else if (err instanceof AgentGuardServerError) {
    // Unexpected server error (5xx)
    console.error(`Server error ${err.statusCode}:`, err.message);
  } else {
    throw err;
  }
}

The SDK automatically retries once on network errors. Auth errors and server errors are never retried.

Example — Express Route

import express from "express";
import { AgentGuard } from "@agentguardorg/node";

const guard = new AgentGuard({ apiKey: process.env.AGENTGUARD_KEY! });
const app = express();
app.use(express.json());

app.post("/agent/send-email", async (req, res) => {
  const { to, body, userId, agentId } = req.body;

  const result = await guard.check({
    action: "send_email",
    payload: { to, body },
    appUserId: userId,
    agentId,
  });

  if (result.decision === "block") {
    return res.status(403).json({ error: result.reason });
  }

  // send the email...
  res.json({ ok: true });
});

Publishing to npm

When you're ready to publish:

cd sdks/node
pnpm run build
npm publish --access public

Make sure your package.json has the correct name, version, and license fields before publishing.

Links

• Dashboard — manage API keys and view logs
• API Reference — raw HTTP API docs
• GitHub — source code and issues