Agent Status SDK for Node.js

Outside-in monitoring for AI agents. Monitor any HTTP-accessible AI agent from distributed residential endpoints worldwide.

Installation

npm install agent-status-sdk
# or
yarn add agent-status-sdk
# or
pnpm add agent-status-sdk

Quick Start

import agentStatus from 'agent-status-sdk';

// Initialize with your API key
agentStatus.init({ apiKey: 'fb_live_xxx' });

// Register an agent for continuous monitoring
const agent = await agentStatus.register({
  endpoint: 'https://api.mycompany.com/chat',
  name: 'Support Bot',
  interval_minutes: 60, // Check every hour
});

console.log(`Registered: ${agent.id}`);

// Check current status
const status = await agentStatus.status(agent.id);
console.log(`Verdict: ${status.verdict}`); // UP, DEGRADED, DOWN
console.log(`Uptime: ${status.uptime_24h}%`);
console.log(`Latency: ${status.latency_p95}ms`);

One-Off Validation

Run a quick validation without registering for continuous monitoring:

const result = await agentStatus.run({
  endpoint: 'https://api.example.com/chat',
  prompts: ['What is 2+2?', 'Hello!'],
});

console.log(`Verdict: ${result.verdict}`);
console.log(`P95 Latency: ${result.latency_p95}ms`);
console.log(`Pass Rate: ${result.pass_rate}`);

Authentication

For agents requiring authentication:

// Bearer token
const agent = await agentStatus.register({
  endpoint: 'https://api.mycompany.com/chat',
  name: 'Private Bot',
  auth: { type: 'bearer', token: 'sk-xxx' },
});

// API key in header
const agent2 = await agentStatus.register({
  endpoint: 'https://api.mycompany.com/chat',
  name: 'API Bot',
  auth: { type: 'api_key', header: 'X-API-Key', value: 'xxx' },
});

Advanced Options

const agent = await agentStatus.register({
  endpoint: 'https://api.mycompany.com/chat',
  name: 'Enterprise Bot',

  // Probing configuration
  interval_minutes: 60,      // How often to probe
  max_nodes_per_run: 10,     // Distributed nodes per check
  geos: ['us', 'eu', 'ap'],  // Geographic regions
  timeout_ms: 30000,         // Request timeout

  // Validation options
  eval_type: 'llm_judge',    // 'basic', 'llm_judge', or 'all'
  gold_prompt_profile: 'search_agent', // Specialized prompts
  inject_geo_context: true,  // Add location to prompts

  // Response handling
  streaming: true,           // SSE streaming responses
});

Direct Client Usage

For more control, use the client directly:

import { AgentStatusClient } from 'agent-status-sdk';

const client = new AgentStatusClient({
  apiKey: 'fb_live_xxx',
  baseUrl: 'https://api.fabric.carmel.so', // optional
  timeout: 60000, // optional
});

const agents = await client.listAgents();

Environment Variables

| Variable | Description | |----------|-------------| | RORA_API_KEY | Your API key (required for CLI) | | RORA_BASE_URL | API base URL override (optional) |

Note: Environment variable names remain RORA_API_KEY and RORA_BASE_URL for backward compatibility.

Types

Agent

interface Agent {
  id: string;
  name: string;
  endpoint_url: string;
  status: 'active' | 'paused' | 'deleted';
  interval_minutes: number;
  last_status?: 'UP' | 'DEGRADED' | 'DOWN';
}

AgentStatus

interface AgentStatus {
  agent_id: string;
  verdict: 'UP' | 'DEGRADED' | 'DOWN' | 'UNKNOWN';
  uptime_24h?: number;
  uptime_7d?: number;
  latency_p50?: number;
  latency_p95?: number;
  pass_rate?: number;
  total_checks: number;
}

RunResult

interface RunResult {
  decision_id: string;
  verdict: 'UP' | 'DEGRADED' | 'DOWN' | 'UNKNOWN';
  latency_p50?: number;
  latency_p95?: number;
  pass_rate?: number;
  total_probes: number;
  successful_probes: number;
  by_region?: RegionBreakdown[];
  judge_result?: JudgeResult;
}

Error Handling

import agentStatus, { AgentStatusError, AgentStatusAuthError, AgentStatusNotFoundError } from 'agent-status-sdk';

try {
  const status = await agentStatus.status('invalid-id');
} catch (error) {
  if (error instanceof AgentStatusNotFoundError) {
    console.log('Agent not found');
  } else if (error instanceof AgentStatusAuthError) {
    console.log('Invalid API key');
  } else if (error instanceof AgentStatusError) {
    console.log(`Error: ${error.message}`);
  }
}

Backward Compatibility

The old RoraClient, RoraError, and RoraConfig names are still exported as aliases:

// These still work
import { RoraClient, RoraError, RoraConfig } from 'agent-status-sdk';

Gold Prompt Profiles

Agent Status uses "gold prompts" - carefully crafted test prompts for different agent types:

| Profile | Description | |---------|-------------| | general | Generic conversational prompts | | search_agent | Web search and information retrieval | | code_generator | Code generation and debugging | | data_retriever | Database and API queries | | customer_support | Support and FAQ handling | | creative_writer | Content generation |

Evaluation Types

| Type | Description | |------|-------------| | basic | Response format and latency checks | | llm_judge | GPT-4 evaluates response quality | | all | Both basic and LLM evaluation |

Links

• Homepage
• Dashboard
• Python SDK
• GitHub

License

MIT