@governancehq/vercel-ai

GaaS (Governance as a Service) integration for the Vercel AI SDK (ai v7).

Every governed tool call submits a governance intent to GaaS before it executes: only an APPROVE (or an approved escalation) lets the tool run.

npm install @governancehq/vercel-ai

Quickstart

import { generateText, stepCountIs } from "ai";
import { governTools, stopOnGovernanceBlock } from "@governancehq/vercel-ai";

const config = { apiKey: "gsk_...", agentId: "my-agent" };

const result = await generateText({
  model,
  tools: governTools({ sendEmail, searchWeb }, config),
  stopWhen: [stepCountIs(5), stopOnGovernanceBlock()],
  prompt: "Email the Q3 report to [email protected]",
});

Verdict semantics (verified against ai@7)

• APPROVE — the tool executes; the run proceeds normally.
• BLOCK — the tool never executes; GovernanceBlockedError is thrown from execute. The AI SDK converts tool errors into tool-error content parts and the generation otherwise continues — the model sees the refusal as an observation and may try again (each retry is re-governed and lands on the signed audit chain server-side).
• stopOnGovernanceBlock() — add to stopWhen to halt the agent loop at the blocked step instead. The run ends with the blocked step as result.steps.at(-1); inspect its tool-error part for the GovernanceBlockedError (decision id, policies, proof token).
• ESCALATE — throws by default; with holdOnEscalate: true the tool call holds while GaaS routes the escalation to a human reviewer: approve/modify proceeds, deny/timeout throws ESCALATE_DENY/ESCALATE_TIMEOUT.

Configuration

const config = {
  apiUrl: "https://api.gaas.is",   // GaaS API endpoint (default)
  apiKey: "gsk_...",               // Your API key (required)
  agentId: "my-agent",             // Appears in the audit trail
  blockOnEscalate: true,           // Throw on ESCALATE (default)
  timeoutMs: 5000,                 // Governance check timeout (fail open)
  sensitivity: "internal",         // Default sensitivity for tool inputs
  raiseOnGovernanceError: false,   // Fail open if GaaS is unreachable (default)
  extraRegulatoryDomains: ["HIPAA"],
  extraDataCategories: ["PHI"],
  holdOnEscalate: false,           // Wait for the human decision on ESCALATE
  escalationPollMs: 5000,
  escalationMaxWaitMs: 600000,
};

Notes

• Tools without an execute function (provider-executed tools) are returned unchanged — they run on the provider's side, out of client-side reach.
• Tool metadata (description, inputSchema, everything else) is preserved; the ToolSet key becomes the tool name on the governance intent.
• Self-contained: no dependency on @governancehq/sdk; ai is a peer dependency.

Links

• Docs: https://gaas.to/sdks.html
• GaaS: https://gaas.is