NexusOS Node.js SDK

Official SDK for NexusOS AI Agent Governance. Monitor, log, and govern AI agents with ease.

Installation

npm install nexusos-sdk

Quick Start

const { NexusAgent } = require('nexusos-sdk');

const agent = new NexusAgent({
  apiKey: 'nxs_live_xxxx',
  agentId: 'nexus_agt_xxxx'
});

// Log an LLM call
await agent.logLLMCall({
  model: 'gpt-4',
  prompt: 'What is the capital of France?',
  response: 'The capital of France is Paris.',
  tokensUsed: 42,
  durationMs: 1200
});

// Send a heartbeat
await agent.heartbeat();

// Cleanup
await agent.destroy();

API Reference

Constructor

const agent = new NexusAgent({
  apiKey,           // (required) API key for NexusOS
  agentId,          // (required) Agent ID
  baseUrl,          // (optional) Base API URL, default: 'https://nexusos-backend-7ue5.onrender.com'
  batchSize,        // (optional) Number of logs to batch before flushing, default: 10
  flushInterval     // (optional) Interval in ms to flush logs, default: 5000
});

Methods

log(payload)

Add a generic log event to the batch queue. Automatically flushes when batch reaches batchSize.

await agent.log({
  event: 'custom.event',
  data: { key: 'value' }
});

logLLMCall({ model, prompt, response, tokensUsed, durationMs })

Log a large language model call.

await agent.logLLMCall({
  model: 'gpt-4',
  prompt: 'Summarize this article...',
  response: 'The article discusses...',
  tokensUsed: 350,
  durationMs: 2500
});

logHttpRequest({ url, method, status, durationMs, success })

Log an HTTP request.

await agent.logHttpRequest({
  url: 'https://api.example.com/data',
  method: 'GET',
  status: 200,
  durationMs: 450,
  success: true
});

logAction({ tool, input, output, durationMs, success, errorMessage })

Log a tool action execution.

await agent.logAction({
  tool: 'web_search',
  input: { query: 'node.js best practices' },
  output: { results: [...] },
  durationMs: 800,
  success: true
});

heartbeat()

Send a heartbeat signal to indicate the agent is alive.

await agent.heartbeat();

isAlive()

Check if the agent is alive by fetching its stats from the API.

const alive = await agent.isAlive();
console.log('Agent is alive:', alive);

trace(name, fn)

Wrap an async function to automatically log its execution time and success/failure.

const result = await agent.trace('process_query', async () => {
  return await processUserQuery();
});

destroy()

Cleanup: stop the batch flusher and flush any remaining logs.

await agent.destroy();

Sensitive Data Handling

The SDK automatically sanitizes logs to remove sensitive information. Keys containing the following terms (case-insensitive) are redacted:

• password
• secret
• key
• token
• auth

Example:

await agent.log({
  username: 'john_doe',
  password: 'super_secret',
  apiKey: 'sk_live_xxx'
});

// Logged as:
// {
//   username: 'john_doe',
//   password: '[REDACTED]',
//   apiKey: '[REDACTED]'
// }

Kill Switch & Pause — IMPORTANT

The NexusOS dashboard gives you a Kill and Pause button for every agent. However, these only work if your agent actually calls isAlive() in its main loop and respects the result.

Without isAlive(), your agent will keep running even after you kill or pause it from the dashboard — logs will just start failing silently.

The Pattern

Wrap your main cycle with an isAlive() check at the top:

const { NexusAgent } = require('nexusos-sdk');

const agent = new NexusAgent({
  apiKey: process.env.NEXUSOS_API_KEY,
  agentId: process.env.NEXUSOS_AGENT_ID,
});

async function runCycle() {
  // ✅ REQUIRED — check kill/pause status before doing any work
  const alive = await agent.isAlive();
  if (!alive) {
    console.log('Agent paused or killed from NexusOS dashboard — skipping cycle');
    return;
  }

  // your agent logic here...
  await agent.heartbeat();
}

// Run on an interval
setInterval(runCycle, 5 * 60 * 1000);
runCycle();

What each status does

| Dashboard Action | isAlive() returns | Effect | |-----------------|---------------------|--------| | Active (default) | true | Agent runs normally | | Pause | false | Cycle is skipped, resumes when you unpause | | Kill | false | Cycle is skipped permanently until process restart |

Note: isAlive() makes a lightweight GET request to NexusOS. Call it once per cycle, not on every log line.

LangChain Integration

Integrate NexusOS with LangChain to automatically monitor LLM calls and tool usage:

const { NexusAgent } = require('nexusos-sdk');
const { LLMChain, OpenAI } = require('langchain');

const agent = new NexusAgent({
  apiKey: 'nxs_live_xxxx',
  agentId: 'nexus_agt_xxxx'
});

const llm = new OpenAI();

// Wrap LLM calls
const originalCall = llm.call.bind(llm);
llm.call = async function(prompt, ...args) {
  const startTime = Date.now();
  try {
    const response = await originalCall(prompt, ...args);
    const durationMs = Date.now() - startTime;

    await agent.logLLMCall({
      model: this.modelName,
      prompt,
      response,
      tokensUsed: response.usage.total_tokens,
      durationMs
    });

    return response;
  } catch (error) {
    const durationMs = Date.now() - startTime;
    await agent.logLLMCall({
      model: this.modelName,
      prompt,
      response: `Error: ${error.message}`,
      tokensUsed: 0,
      durationMs
    });
    throw error;
  }
};

OpenAI Integration

Monitor OpenAI API calls:

const { NexusAgent } = require('nexusos-sdk');
const { Configuration, OpenAIApi } = require('openai');

const agent = new NexusAgent({
  apiKey: 'nxs_live_xxxx',
  agentId: 'nexus_agt_xxxx'
});

const openai = new OpenAIApi(new Configuration({
  apiKey: process.env.OPENAI_API_KEY
}));

async function callOpenAI(prompt) {
  const startTime = Date.now();

  try {
    const response = await openai.createChatCompletion({
      model: 'gpt-4',
      messages: [{ role: 'user', content: prompt }]
    });

    const durationMs = Date.now() - startTime;
    const tokensUsed = response.data.usage.total_tokens;

    await agent.logLLMCall({
      model: 'gpt-4',
      prompt,
      response: response.data.choices[0].message.content,
      tokensUsed,
      durationMs
    });

    return response.data;
  } catch (error) {
    const durationMs = Date.now() - startTime;

    await agent.logLLMCall({
      model: 'gpt-4',
      prompt,
      response: `Error: ${error.message}`,
      tokensUsed: 0,
      durationMs
    });

    throw error;
  }
}

Environment Variables

Configure the SDK using environment variables:

export NEXUSOS_API_KEY=nxs_live_xxxx
export NEXUSOS_AGENT_ID=nexus_agt_xxxx
export NEXUSOS_BASE_URL=https://nexusos-backend-7ue5.onrender.com

const agent = new NexusAgent({
  apiKey: process.env.NEXUSOS_API_KEY,
  agentId: process.env.NEXUSOS_AGENT_ID,
  baseUrl: process.env.NEXUSOS_BASE_URL
});

License

MIT