Core Functions

API reference for createGovernance, register, enforce, score, and scoreFleet.

The primary API surface of governance-sdk — create an instance, register agents, enforce policies, and inspect state.

createGovernance(options)

import { createGovernance } from 'governance-sdk'

Creates a governance instance that holds your policy rules, registered agents, and audit trail. Export as a singleton so all agents share the same policy set.

createGovernance({ rules?, storage?, defaultOutcome?, serverUrl?, apiKey? }) => GovernanceInstance

Parameters:

rules? — Array of policy rules (blockTools, requireApproval, etc.)
storage? — Storage backend. Defaults to in-memory. Use createPostgresStorage for persistence.
defaultOutcome? — Default outcome when no rules match: "allow" or "block".

import { createGovernance, blockTools, requireApproval } from 'governance-sdk';

const gov = createGovernance({
  rules: [
    blockTools(['shell_exec', 'db_drop', 'fs_write']),
    requireApproval(['payment', 'data_access']),
  ],
});

Note: Rules are evaluated in priority order. Higher priority wins when multiple rules match the same tool.

gov.register(agent)

async — returns registration result with governance score

Registers an agent with the governance instance. Computes a 7-dimension governance score instantly and assigns a level (L0 through L4).

gov.register({ name, framework?, owner, tools?, hasAuth?, hasGuardrails?, hasObservability?, hasAuditLog? })
  => { id, score, level, status, assessment }

const result = await gov.register({
  name: 'sales-agent',
  framework: 'mastra',
  owner: 'sales-team',
  tools: ['email_draft', 'crm_update', 'calendar_book'],
  hasAuth: true,
  hasGuardrails: true,
  hasAuditLog: true,
});

// result.id         → "agent_a1b2c3..."
// result.score      → 68
// result.level      → 3
// result.status     → "approved"
// result.assessment → { compositeScore: 68, level: {...}, dimensions: [...] }

gov.enforce(ctx)

async — evaluates policies and writes to audit trail

Evaluates all matching policy rules before a tool call executes. Returns an EnforcementDecision with blocked, reason, outcome, and more. Every call is automatically recorded in the audit trail.

gov.enforce(ctx: EnforcementContext)
  => EnforcementDecision { blocked, reason, ruleId, outcome, evaluatedAt, rulesEvaluated }

// Blocked — shell_exec matches blockTools rule
const d1 = await gov.enforce({
  agentId: result.id,
  action: 'tool_call',
  tool: 'shell_exec',
});
// d1.blocked  → true
// d1.outcome  → "block"
// d1.ruleId   → "blockTools"
// d1.reason   → "Tool 'shell_exec' is blocked by policy"

// Allowed — email_send is not in any deny list
const d2 = await gov.enforce({
  agentId: result.id,
  action: 'tool_call',
  tool: 'email_send',
});
// d2.blocked → false
// d2.outcome → "allow"

Note: If multiple rules match, the highest-priority rule wins. Kill switch rules always evaluate at priority 999.

gov.storage.getAgent(agentId)

returns the registered agent or undefined

Retrieves a registered agent by ID including name, tools, score, and registration metadata. Returns undefined if not found.

gov.storage.getAgent(agentId: string) => Agent | undefined

const agent = gov.storage.getAgent(result.id);

if (agent) {
  // agent.name       → "sales-agent"
  // agent.score      → 68
  // agent.level      → 3
  // agent.tools      → ["email_draft", "crm_update", "calendar_book"]
  // agent.framework  → "mastra"
}

gov.audit.query(filters)

query the audit trail with optional filters

Query audit entries from enforce() calls. Each entry includes a timestamp, agent ID, tool, decision, and metadata. Use gov.audit.log(event) to write custom entries and gov.audit.count(filters?) to count entries.

gov.audit.query(filters?) => AuditEntry[]

const trail = await gov.audit.query({ agentId: result.id });

// trail[0]:
// {
//   timestamp: "2026-03-10T12:00:00.000Z",
//   agentId: "agent_a1b2c3...",
//   action: "tool_call",
//   tool: "shell_exec",
//   outcome: "block",
//   rule: "blockTools",
// }

// Log a custom event
await gov.audit.log({ agentId: result.id, action: 'custom_event', tool: 'manual' });

// Count entries
const count = await gov.audit.count({ agentId: result.id });

Note: Use createIntegrityAudit() from Integrity Audit for HMAC-SHA256 tamper-evident audit chains with verify() support.