Back to Documentation
Sdk QuickstartUpdated 2026-03-15

SDK Quickstart: Getting Started

Install and configure the Vorion trust engine and Cognigate client in under 5 minutes.

SDK Quickstart

Get up and running with the Vorion AI governance stack. This guide covers installing @vorionsys/atsf-core (the trust engine) and @vorionsys/cognigate (the governance enforcement engine client), then wiring them together.

Prerequisites

  • Node.js >= 18.0.0
  • TypeScript >= 5.0.0
  • A Cognigate API key (get one at cognigate.dev)

1. Install Packages

npm install @vorionsys/atsf-core @vorionsys/cognigate

@vorionsys/atsf-core is the core trust scoring runtime. @vorionsys/cognigate is the TypeScript client SDK for the Cognigate governance enforcement API.

2. Create a Trust Engine

The trust engine evaluates agent behavior across multiple dimensions and assigns a trust score (0--1000) mapped to one of eight tiers (T0 Sandbox through T7 Autonomous).

import { createTrustEngine } from '@vorionsys/atsf-core';

const engine = createTrustEngine({
  failureThreshold: 0.3,   // Signals below 0.3 count as failures
  successThreshold: 0.7,   // Signals above 0.7 count as successes
  gainRate: 0.05,           // Logarithmic gain rate per success signal
});

// Initialize an agent at T1 (Observed) -- score starts at 200
const agent = await engine.initializeEntity('agent-001', 1);
console.log(agent.score);  // 200
console.log(agent.level);  // 1

Record Behavioral Signals

Trust is earned through demonstrated competence. Record signals as agents complete tasks:

await engine.recordSignal({
  id: crypto.randomUUID(),
  entityId: 'agent-001',
  type: 'behavioral.task_completed',
  value: 0.9,              // 0.0 = total failure, 1.0 = perfect
  source: 'system',
  timestamp: new Date().toISOString(),
  metadata: { task: 'data-analysis' },
});

// Recalculate trust
const calc = await engine.calculate('agent-001');
console.log(`Score: ${calc.score}, Tier: T${calc.level}`);

Listen for Tier Changes

engine.on('trust:tier_changed', (event) => {
  console.log(
    `${event.entityId} ${event.direction}: ` +
    `${event.previousLevelName} -> ${event.newLevelName}`
  );
});

3. Connect the Cognigate Client

Cognigate sits between your AI agents and the actions they want to perform, enforcing trust-based governance in real time.

import { Cognigate } from '@vorionsys/cognigate';

const client = new Cognigate({
  apiKey: process.env.COGNIGATE_API_KEY!,
  // baseUrl defaults to https://cognigate.dev/v1
});

Register an Agent

const registeredAgent = await client.agents.create({
  name: 'DataProcessor',
  description: 'ETL pipeline agent',
  initialCapabilities: ['read_database', 'write_s3'],
});

Check Trust Status

const status = await client.trust.getStatus(registeredAgent.id);
console.log(`Trust Score: ${status.trustScore}`);
console.log(`Tier: ${status.tierName}`);
console.log(`Capabilities: ${status.capabilities.join(', ')}`);

Evaluate a Governance Request

The evaluate method parses intent from natural language and enforces governance policies in a single call:

const { intent, result } = await client.governance.evaluate(
  registeredAgent.id,
  'Read customer data from the sales database'
);

if (result.decision === 'ALLOW') {
  console.log('Proceeding -- granted:', result.grantedCapabilities);
} else if (result.decision === 'ESCALATE') {
  console.log('Needs human approval:', result.reasoning);
} else if (result.decision === 'DEGRADE') {
  console.log('Partial access:', result.grantedCapabilities);
} else {
  console.log('Blocked:', result.reasoning);
}

4. Wire Up the Proof Chain

Every governance decision is recorded as an immutable, hash-chained proof record.

// Query proof records
const proofs = await client.proofs.list(registeredAgent.id, {
  from: new Date('2026-01-01'),
  pageSize: 50,
});

// Verify chain integrity
const verification = await client.proofs.verify(registeredAgent.id);
console.log('Chain valid:', verification.valid);

Trust Tiers Reference

| Tier | Score Range | Name | Description | |------|-------------|-------------|------------------------------------------| | T0 | 0--199 | Sandbox | Isolated testing, no real operations | | T1 | 200--349 | Observed | Read-only, under active supervision | | T2 | 350--499 | Provisional | Basic operations, heavy constraints | | T3 | 500--649 | Monitored | Standard operations, continuous monitoring| | T4 | 650--799 | Standard | External API access, policy-governed | | T5 | 800--875 | Trusted | Cross-agent communication | | T6 | 876--950 | Certified | Admin tasks, minimal oversight | | T7 | 951--1000 | Autonomous | Full autonomy, self-governance |

Next Steps

All Documentation