Concepts

The mental model behind governance-sdk. Understand these four concepts and you understand the entire SDK.

Agents

An agent is any autonomous program that makes decisions and takes actions — calling tools, sending messages, executing code. In governance-sdk, every agent is registered with gov.register() and receives a unique ID, a 7-dimension governance score, and a maturity level (L0–L4).

Registration is framework-agnostic. Whether your agent runs on Mastra, Vercel AI SDK, LangChain, or a custom loop — the governance layer doesn't care. It only cares about what the agent does.

const agent = await gov.register({
  name: 'payment-agent',
  framework: 'mastra',
  tools: ['check_balance', 'send_invoice'],
  hasAuth: true,
  hasGuardrails: true,
});
// agent.score = 68, agent.level = 3 ("Governed")

Policies

A policy is a declarative rule that controls what agents can do. Policies are evaluated before every action — not after. They define conditions (what to check) and outcomes (allow, block, or require approval).

8 built-in presets cover 90% of use cases. For complex scenarios, compose them with boolean combinators (any_of, all_of, not) or write custom conditions.

Deep dive: Policies & Rules

Enforcement

Enforcement is the core loop. Every time an agent wants to do something, call gov.enforce(). The SDK evaluates all policies against the proposed action and returns allow or block — in under 1ms, with zero network calls.

1. Agent requests action — e.g. tool_call: shell_exec
2. enforce() intercepts — Before execution, less than 1ms
3. BLOCKED or ALLOWED — Policy matched → action stopped, or all rules pass → proceed
4. Audit logged — HMAC-chained event recorded automatically

Every enforcement decision is automatically written to the audit trail — no extra code needed.

Scoring

Every registered agent gets a governance score (0–100) computed across 7 dimensions: authentication, guardrails, observability, tool scoping, audit logging, human oversight, and compliance. The score maps to a governance level:

Deep dive: Governance Scoring

Architecture: Thin Client

governance-sdk is a thin client SDK. Policy evaluation, scoring, injection detection, and adapter logic all run locally in your process — no network calls, no external services, no latency.