tethora-sdk

Official SDK for Tethora - the AI agent governance and compliance platform.

Log every AI agent action, enforce policy guardrails, and generate compliance reports for EU AI Act, GDPR, SOC 2, ISO 42001, NIST AI RMF, PCI DSS, and HIPAA.

Install

npm install tethora-sdk

Quick Start

import { Tethora } from 'tethora-sdk';

const tethora = new Tethora({
  apiKey: 'your-api-key',
});

// Log an agent action
tethora.log({
  eventType: 'tool_call',
  action: 'send_email',
  toolName: 'gmail_send',
  input: { to: '[email protected]' },
});

Tracing with Policy Enforcement

Wrap async operations with trace() to automatically check policies before execution, capture duration, output, and errors:

const result = await tethora.trace('llm_call', {
  toolName: 'gpt-4',
  action: 'generate_response',
  fn: async () => {
    return await openai.chat.completions.create({
      model: 'gpt-4',
      messages: [{ role: 'user', content: 'Hello' }],
    });
  },
});

Before fn() runs, the SDK checks your policies. If a policy blocks the action, fn() is never called and a BlockedError is thrown. If the action is allowed, it produces two events: generate_response (start) and generate_response.complete (with duration and output). If the function throws, a generate_response.error event is logged and the error is re-thrown.

Handling blocked actions

import { Tethora, BlockedError } from 'tethora-sdk';

try {
  await tethora.trace('tool_call', {
    toolName: 'sendgrid',
    action: 'send_email',
    fn: () => sendEmail(to, subject, body),
  });
} catch (err) {
  if (err instanceof BlockedError) {
    console.log('Policy blocked this action:', err.violations);
    // err.violations contains the policy names and reasons
  }
}

Skipping the policy check

For non-critical actions where you want logging without enforcement:

await tethora.trace('tool_call', {
  toolName: 'logger',
  action: 'write_log',
  skipCheck: true, // Log only, no policy check
  fn: () => writeLog(message),
});

Pre-execution policy check

You can also check policies manually without using trace():

const { outcome, violations } = await tethora.check({
  eventType: 'tool_call',
  toolName: 'postgres_query',
  action: 'delete_records',
});

if (outcome === 'blocked') {
  console.log('Blocked by:', violations);
} else {
  await deleteRecords();
}

Configuration

const tethora = new Tethora({
  apiKey: 'your-api-key',       // Required
  agentId: 'agent-uuid',        // Optional: default agent for all events
  agentExternalId: 'my-bot-v2', // Optional: your internal agent ID
  baseUrl: 'https://api.tethora.ai', // Optional: defaults to production
  batchSize: 50,                // Optional: events per batch (default 50)
  flushIntervalMs: 2000,        // Optional: auto-flush interval (default 2s)
});

Event Fields

tethora.log({
  eventType: 'tool_call',       // Required
  action: 'search_database',    // What the agent did
  toolName: 'postgres_query',   // Tool or function used
  input: { query: '...' },      // Input data (any JSON)
  output: { rows: 42 },         // Output data (any JSON)
  durationMs: 150,              // Execution time in ms
  sessionId: 'session-123',     // Group events by session
  agentId: 'agent-uuid',        // Override default agent
  occurredAt: new Date().toISOString(), // When it happened
});

Methods

| Method | Description | |--------|-------------| | log(event) | Queue an event for batch ingestion. Never throws. | | trace(type, opts) | Check policies, execute function, and log events. Throws BlockedError if blocked. | | check(event) | Pre-execution policy check. Returns { outcome, violations }. | | flush() | Send queued events immediately (fire-and-forget) | | flushAsync() | Send queued events and return the response | | destroy() | Clean up timers. Call on shutdown. |

Framework Integrations

For automatic instrumentation without manual log() calls:

• @tethora/openai - OpenAI SDK wrapper
• @tethora/langchain - LangChain callback handler
• @tethora/ai-sdk - Vercel AI SDK middleware

Links

• Documentation
• Compliance Frameworks
• Pricing

Licence

MIT