Connect your agents to Oceum

Quick Start

Get your API key from Settings and your agent ID from the Agents page once you sign in to the portal.

const { Oceum } = require('oceum');

const client = new Oceum({
  apiKey: process.env.OCEUM_API_KEY,
  agentId: process.env.OCEUM_AGENT_ID,
});

// Start auto-heartbeat (every 60s)
client.startHeartbeat();

// Wrap tasks: auto logs start, complete, and errors
const result = await client.wrap('Process leads', async () => {
  const leads = await fetchLeads();
  await processAll(leads);
  return leads.length;
});

// Clean up
client.stopHeartbeat();
await client.setStatus('idle');

Configuration

The Oceum constructor accepts a configuration object with these properties:

API Reference

const result = await client.wrap('Sync contacts', async () => {
  const contacts = await crm.fetchAll();
  await db.upsertMany(contacts);
  return contacts.length;
});

Knowledge Infrastructure

Orion's intelligence is grounded in a RAG (Retrieval-Augmented Generation) pipeline that ensures every response is factual, sourced, and org-scoped. No hallucinations. Every answer cites its sources.

How It Works

When a user or agent asks Orion a question, the system embeds the query, searches for relevant knowledge chunks via hybrid search (vector similarity + keyword matching), and injects the most relevant context into the LLM prompt. Orion reasons over retrieved facts: it never invents.

Knowledge Tiers

Enterprise Knowledge Management

Upload your own documents via POST /api/knowledge. Documents go through an approval workflow (draft → approved → active) and are versioned with full rollback support. Only active documents appear in retrieval results.

Source Attribution

Every Orion response includes source citations: document name, section, and freshness date. You always know where the answer came from and how current it is.

Advanced Retrieval

Hybrid search combines vector similarity (pgvector HNSW) with keyword matching (PostgreSQL tsvector) via Reciprocal Rank Fusion. Optional Cohere Rerank further refines results. Adaptive top-K retrieval adjusts to query complexity within a strict 1,500-token context budget.

Event Types

Every SDK method sends a webhook event to POST /api/webhook. Here's what each event does server-side:

Framework Examples

The SDK works with any Node.js agent framework. Here are integration patterns for popular ones:

const { Oceum } = require('oceum');
const { ChatOpenAI } = require('@langchain/openai');

const oceum = new Oceum({
  apiKey: process.env.OCEUM_API_KEY,
  agentId: process.env.OCEUM_AGENT_ID,
});

oceum.startHeartbeat();

const model = new ChatOpenAI({ model: 'gpt-4o' });

const answer = await oceum.wrap('Chat completion', async () => {
  const res = await model.invoke('Summarize Q1 revenue');
  return res.content;
});

// Node.js wrapper around a CrewAI Python process
const { Oceum } = require('oceum');
const { execSync } = require('child_process');

const oceum = new Oceum({
  apiKey: process.env.OCEUM_API_KEY,
  agentId: process.env.OCEUM_AGENT_ID,
});

const result = await oceum.wrap('Research crew', async () => {
  const output = execSync('python crew.py --topic "AI trends"');
  return output.toString();
}, { crew: 'research', agents: 3 });

const { Oceum } = require('oceum');

const oceum = new Oceum({
  apiKey: process.env.OCEUM_API_KEY,
  agentId: process.env.OCEUM_AGENT_ID,
});

oceum.startHeartbeat(30000); // every 30s

while (true) {
  const job = await queue.dequeue();
  if (!job) {
    await oceum.setStatus('idle');
    await sleep(5000);
    continue;
  }

  await oceum.wrap(job.name, async () => {
    await processJob(job);
  }, { jobId: job.id });
}

// On shutdown
oceum.stopHeartbeat();
await oceum.setStatus('offline');

Pulse System

The Autonomous Pulse System gives your agent estate persistent awareness. Agents record observations between scheduled runs. Every 5 minutes, the Pulse cron synthesizes platform state and decides whether to act or stay quiet.

Agent Observations

Each agent cron records 0–3 observations per run using heuristic thresholds, no LLM calls required. Observations flow into the agent_observations table, scoped to your organization.

// Record an observation from your agent
const { recordObservation } = require('./pulse-engine');

await recordObservation(supabase, {
  orgId: 'your-org-id',
  agentId: 'agt_your_agent',
  observationType: 'anomaly',
  content: 'Error rate exceeded 5% threshold',
  confidence: 0.85,
  sourceContext: { errorRate: 0.07, threshold: 0.05 }
});

Pulse Evaluation

The Pulse cron builds a situation snapshot every 5 minutes. If the snapshot hash matches the previous tick, the LLM call is skipped entirely: eliminating ~90% of unnecessary API calls. When changes are detected, a single Haiku call decides: act or stay quiet.

Confidence-Gated Notifications

Notifications flow through a two-tier gate. Immediate alerts fire only when confidence exceeds 0.95 and severity is critical (max 3/day). Everything else is batched into a daily digest. Per-topic cooldowns prevent repeated alerts on the same issue.

Agent Journal

Every decision is recorded in an append-only journal with full reasoning. No UPDATE or DELETE permitted. Event types: noticed, decided, acted, deferred, consolidated, pruned, promoted.

Error Handling

All methods throw an OceumError when the API returns a non-2xx status code. The error includes the HTTP status code and the response body for programmatic handling.

const { Oceum, OceumError } = require('oceum');

try {
  await client.heartbeat();
} catch (err) {
  if (err instanceof OceumError) {
    if (err.statusCode === 401) {
      console.error('Invalid API key');
    } else if (err.statusCode === 404) {
      console.error('Agent not found: check your agent ID');
    }
  }
}

Common Error Codes