← Back to Blog

Embed AI Agents in Your Node.js App with OE Runtime SDK

The OE Runtime SDK lets you call AI agents directly from Node.js code — no CLI subprocess, no HTTP server, no extra process. One require(), one function call, full agent execution.

Three Ways to Run OE Runtime Agents

OE Runtime has always supported three delivery modes. Each runs the same YAML agent with identical results:

Mode	How	Best for
CLI	npx @openenthrium/oe-runtime@latest agent.yaml	Scripts, cron jobs, pipelines
HTTP API	--serve + POST /run-file	Web services, mobile backends, any language
Node.js SDK	require("@openenthrium/oe-runtime-sdk")	Node.js apps that want in-process execution

The SDK is the right choice when you are already building a Node.js application and want agent execution to feel like a native function call — not a shell command or an HTTP request.

Install

npm install @openenthrium/oe-runtime-sdk

That is everything. The SDK bundles the full OE Runtime engine. Connector packages (pg, mongodb, mysql2, kafkajs, etc.) are optional peer dependencies — install only the ones your agents use.

Run an Agent from Files

The simplest path: point the SDK at your agent.yaml and oe-config.json and call runAgent().

const { runAgent } = require("@openenthrium/oe-runtime-sdk");

// agent.yaml  — YAML agent definition (any OE Runtime agent file)
// oe-config.json — LLM key + connector credentials
// params — replaces {{company}} in the agent's instructions and steps
// hooks  — optional callbacks for tool calls and results

async function main() {
  const result = await runAgent(
    "./agents/sales-report.yaml",
    "./oe-config.json",
    { company: "Acme Corp" },
    {
      onToolCall:   (name)         => console.log(`🔧 calling ${name}`),
      onToolResult: (name, result) => console.log(`   ↳ ${result.slice(0, 200)}`),
    }
  );

  console.log(result.output);
}

main().catch(console.error);

Run an Agent from Objects (No Files)

For dynamic agents built at runtime — or when you want to store agents in a database rather than on disk — use runAgentFromObject(). Pass the parsed YAML and config directly as JavaScript objects.

const { runAgentFromObject } = require("@openenthrium/oe-runtime-sdk");

const agentYaml = {
  name: "Sales Summary Agent",
  instructions: "You are a data analyst. Query the database and summarise this week's sales.",
  steps: [
    { name: "Query",  content: "Run a SELECT on the orders table for the last 7 days." },
    { name: "Report", content: "Write a 3-paragraph executive summary of the results." },
  ],
  connectors: [
    { connection_name: "Sales DB", connection_type: "postgresql" }
  ],
};

const config = {
  llm: {
    provider: "anthropic",
    apiKey:   process.env.ANTHROPIC_KEY,
    model:    "claude-opus-5",
  },
  connectors: [{
    connection_name: "Sales DB",
    connection_type: "postgresql",
    host:     "db.internal",
    database: "sales",
    user:     "readonly",
    password: process.env.DB_PASSWORD,
  }],
};

const { output } = await runAgentFromObject(agentYaml, config);
console.log(output);

Use in an Express or Fastify Route

The SDK returns a plain Promise, so it drops into any async route handler without ceremony.

const express = require("express");
const { runAgent } = require("@openenthrium/oe-runtime-sdk");

const app = express();
app.use(express.json());

app.post("/generate-report", async (req, res) => {
  const { company } = req.body;

  const { output } = await runAgent(
    "./agents/weekly-report.yaml",
    "./oe-config.json",
    { company }
  );

  res.json({ report: output });
});

app.listen(3000);

Available Hooks

The fourth argument to both runAgent and runAgentFromObject is a hooks object. All hooks are optional.

Hook	When it fires	Arguments
onToolCall	Before each connector tool call	(toolName)
onToolResult	After each connector tool call	(toolName, resultText)
onDone	When the agent finishes	(output)
onError	On any unhandled error	(error)

Install Only What You Need

The SDK does not bundle database drivers or cloud SDK clients. Every connector package is an optional peer dependency — you only install the ones your agents actually use:

# PostgreSQL agents
npm install pg

# MongoDB agents
npm install mongodb

# MySQL agents
npm install mysql2

# Kafka agents
npm install kafkajs

# S3 agents
npm install @aws-sdk/client-s3

If you try to run an agent that uses a connector whose package is not installed, the SDK throws a clear error telling you which package to add.

Same Agent YAML — All Three Modes

The strongest feature of the SDK is not the API — it is portability. Every agent.yaml file runs identically on all three surfaces without any changes:

• CLI — npx @openenthrium/oe-runtime@latest ./skill-folder-name for automation and cron
• HTTP API — --serve mode for web services in any language including Python, Go, and PHP
• SDK — runAgent() for Node.js apps that want in-process execution

Write the agent once. Deploy it everywhere. No rewrites, no adapter layers, no platform lock-in.

---