agent-guardrails

Laat AI-agents veilig falen. Omhul de acties van een agent — tool calls, shell commands, model-outputs — met invarianten, kostenlimieten en een begrensde tool-scope. Een blokkerende overtreding stopt de actie voordat die wordt uitgevoerd.

~3 KB · Node 18+ · zonder deps · binnenkort open-source — mail me voor vroege toegang

Waarom

AI-agents demonstreren prachtig en falen in productie — zelden door modelkwaliteit, bijna altijd door de operationele laag rond het model: onbegrensde scope, op hol geslagen kosten, destructieve tool calls, gelekte secrets, geen stop wanneer de agent ontspoort. De agents die het écht halen delen drie eigenschappen: begrensde scope, guardrails, en een harde stop bij overtreding. Dit is die laag, in één klein bestand.

Quickstart

import { createGuard, allowTools, denyDestructive, noSecrets, maxCost }
  from '@paulodevries/agent-guardrails';

const guard = createGuard([
  allowTools(['search', 'read_file', 'bash']), // bounded scope
  denyDestructive(),                            // no rm -rf /, DROP DATABASE…
  noSecrets(),                                  // never let a credential through
  maxCost(2.00),                                // cap cumulative spend
]);

// execute() only runs if every guardrail passes:
const { result } = await guard.run(
  { tool: 'bash', input: 'ls -la', cost: 0.001 },
  (action) => runTool(action),
);

// A blocking violation throws before runTool is ever called:
await guard.run({ tool: 'bash', input: 'rm -rf /' }, runTool); // ✗

Ingebouwde guardrails

Je eigen guardrail schrijven is één functie: { name, check(action) } die true retourneert, een reden-string, of { reason, severity:'warn' }.

Gebouwd op patronen die bewezen zijn door een autonoom multi-agent-systeem onbeheerd te draaien over 40+ projecten. Combineert met agent-eval → (de test-time-helft) tot een tweedelige betrouwbaarheids-toolkit. De denkwijze achter beide: Betrouwbaarheid van agents is een guardrails-probleem, geen modelprobleem →. Feedback + PR's welkom.

Vragen

Wat is agent-guardrails?

Een JavaScript-library zonder dependencies die de acties van een AI-agent — tool calls, shell commands, model-outputs — omhult met invarianten, kostenlimieten en een begrensde tool-scope. Een blokkerende overtreding stopt de actie voordat die wordt uitgevoerd, zodat de onveilige call nooit draait. Ongeveer 3 KB, Node 18+, MIT-gelicentieerd.

Hoe voorkom je dat een AI-agent een destructief commando uitvoert?

Omhul elke actie in een guard die hem vóór uitvoering controleert. De ingebouwde guardrails dekken de veelvoorkomende fouten af: allowTools begrenst de scope tot een allowlist, denyDestructive blokkeert rm -rf /, DROP DATABASE, force-push naar main en sudo, noSecrets blokkeert gelekte credentials, en maxCost / maxCalls beperken uitgaven en op hol geslagen loops. Een blokkerende check gooit een error voordat de tool ooit draait; warnOn markeert een actie zonder die te stoppen.

Waarom falen AI-agents in productie?

Zelden door modelkwaliteit — bijna altijd door de operationele laag rond het model: onbegrensde scope, op hol geslagen kosten, destructieve tool calls, gelekte secrets, en geen harde stop wanneer de agent ontspoort. De agents die het écht halen delen drie eigenschappen: begrensde scope, guardrails, en een harde stop bij overtreding. Deze patronen komen voort uit het onbeheerd draaien van een autonoom multi-agent-systeem over 40+ projecten.