@runtimeai/sdk

Official TypeScript SDK for the RuntimeAI Control Plane — govern, secure, and observe AI agents at scale.

Installation

npm install @runtimeai/sdk

Quick Start

import { RuntimeAI } from '@runtimeai/sdk';

const client = new RuntimeAI({
  apiUrl: 'https://api.rt19.runtimeai.io',
  apiKey: process.env.RUNTIMEAI_API_KEY!,
});

// Register an AI agent
const agent = await client.agents.register({
  name: 'contract-analyzer',
  type: 'langchain',
  owner: '[email protected]',
  risk_level: 'medium',
});
console.log(`Agent registered: ${agent.id}`);

// Discover shadow AI usage
const { findings } = await client.discovery.listFindings();
console.log(`Found ${findings.length} shadow AI instances`);

// Track costs
await client.finops.reportUsage({
  agent_id: agent.id,
  model: 'gpt-4',
  provider: 'openai',
  input_tokens: 1500,
  output_tokens: 800,
  cost_usd: 0.045,
});

// Check compliance posture
const { frameworks } = await client.compliance.listFrameworks();
for (const fw of frameworks) {
  console.log(`${fw.name}: ${fw.compliance_pct}% compliant`);
}

Authentication

API Key

const client = new RuntimeAI({
  apiUrl: 'https://api.your-pod.runtimeai.io',
  apiKey: 'your-api-key', // X-API-Key header
});

JWT Token

const client = new RuntimeAI({
  apiUrl: 'https://api.your-pod.runtimeai.io',
  authToken: 'your-jwt-token', // Authorization: Bearer header
  tenantId: 'your-tenant-id',  // X-Tenant-ID header
});

Available Clients

| Client | Methods | |--------|---------| | client.agents | register, list, get, update, killSwitch, getTrustScore, heartbeat | | client.discovery | listFindings, triageFinding, listScanners, configureScanner, ingest | | client.finops | reportUsage, getUsageSummary, listBudgets, setBudget, getCostAttribution | | client.policies | listGuardrails, createGuardrail, listSodRules, listConditionalAccess, evaluate | | client.mcp | listTools, registerTool, invokeTool, listConnections, getTopology | | client.compliance | listFrameworks, listGaps, uploadEvidence, listRiskScores | | client.audit | list, search, get |

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiUrl | string | — | Required. Control Plane API URL | | apiKey | string | — | API key (X-API-Key header) | | authToken | string | — | JWT token (Bearer header) | | tenantId | string | — | Tenant ID for multi-tenant ops | | timeout | number | 30000 | HTTP timeout in ms | | maxRetries | number | 2 | Max retries on 5xx errors |

Error Handling

import { RuntimeAI, RuntimeAIError } from '@runtimeai/sdk';

try {
  const agent = await client.agents.get('nonexistent-id');
} catch (error) {
  if (error instanceof RuntimeAIError) {
    console.error(`API Error: ${error.statusCode} ${error.code} — ${error.message}`);
  }
}

Requirements

• Node.js >= 18.0.0 (uses native fetch)
• Zero runtime dependencies

License

MIT © RuntimeAI