@identiqube/provenant-sdk

The few lines an autonomous agent adds to become governable. The SDK wraps the Provenant action gateway: authorize, simulate, and complete.

import { ProvenantClient } from '@identiqube/provenant-sdk';

const provenant = new ProvenantClient({
  baseUrl: process.env.PROVENANT_API!,
  apiKey: process.env.PROVENANT_KEY!, // per-agent key, shown once at creation
});

// 1. Ask before acting.
const decision = await provenant.authorize({
  type: 'payment.send',
  resource: 'vendor:acme',
  valueCents: 2_500,
});

// 2. Branch on the decision (a `deny` is returned, not thrown).
if (decision.status === 'authorized') {
  const externalRef = await payVendor(/* ... */);
  // 3. Report the real-world outcome.
  await provenant.complete(decision.id, { success: true, externalRef });
} else if (decision.status === 'pending_approval') {
  // held for a human — approvalId is on decision.approvalId
} else {
  console.warn('denied:', decision.decision.reason);
}

guard helper

Authorize, run, and report completion in one call:

const { authorized, result } = await provenant.guard(
  { type: 'payment.send', resource: 'vendor:acme', valueCents: 2_500 },
  async () => ({ result: await payVendor(), externalRef: 'ext_123' }),
);

Governed tools (any framework)

governTool wraps a tool's executor so every call is authorized, executed, and completed through Provenant — with no framework dependency. Drop it into the Vercel AI SDK, LangChain, OpenAI function-calling, or a plain async (args) => result.

import { ProvenantClient, governTool } from '@identiqube/provenant-sdk';
import { tool } from 'ai'; // Vercel AI SDK
import { z } from 'zod';

const pay = tool({
  description: 'Pay a vendor invoice',
  parameters: z.object({ vendor: z.string(), amountCents: z.number() }),
  execute: governTool(provenant, payVendor, {
    type: 'payment.send',
    resource: (a) => `vendor:${a.vendor}`,
    valueCents: (a) => a.amountCents,
  }),
});

// LangChain: wrap the tool's func the same way.
new DynamicStructuredTool({
  name: 'pay', description: 'Pay a vendor', schema,
  func: governTool(provenant, payVendor, { type: 'payment.send', resource: (a) => `vendor:${a.vendor}`, valueCents: (a) => a.amountCents }),
});

When policy allows, the tool runs and the outcome is reported automatically. When it denies or holds for approval, the tool never runs and the call resolves to a GovernBlocked object the model reads as the tool result:

{ "provenant": "blocked", "status": "denied", "reason": "over budget",
  "approvalId": null, "actionId": "act_2" }

The agent then explains the refusal (or that it's awaiting a human) instead of acting — a clean, on-brand deny rather than an exception.

Dry-run

const sim = await provenant.simulate({ type: 'payment.send', resource: 'vendor:acme', valueCents: 9_999 });
console.log(sim.decision.effect, sim.budgetImpact);

authorize/simulate/complete throw a ProvenantError only on auth/validation/network failures — a policy denial is a normal decision returned on the result so the agent can branch on decision.status.