Skip to content
Night Owls.dev
GitHubGet started
Jump to a page

@nightowlsdev/engine-openai-agents

EngineNative

The third native engine, a governed @openai/agents run() loop with full governance (fail-closed tool gate, cost caps, secrets), native handoffs/guardrails. Single-agent v1 (multi-agent handoffs planned v1.1).

What it does

@nightowlsdev/engine-openai-agents is the third NATIVE engine in the `engine-*` family (alongside `engine-mastra` and `engine-ai-sdk`): a from-scratch swarm loop built directly on the OpenAI Agents SDK (`@openai/agents` `run()`) instead of Mastra or the raw Vercel AI SDK. It reuses the SAME governance plane as its native siblings, `HookDispatcher`/`ToolApprovalPolicy` (preGeneration reserve + preToolCall fail-closed backstop), `CostGovernor`/pricing, tier routing, secrets, telemetry, and its `governance.preGeneration: true` claim is NOT a leap of faith: a spike verified the SDK's `RunConfig.callModelInputFilter` fires exactly once per model launch and a thrown error aborts the run cleanly (never a stranded/partial generation), so the full-governance claim stands on `OPENAI_AGENTS_ENGINE_CAPABILITIES`. Tool approvals map onto the SDK's native boolean-approve/reject tool-approval interruption; cancellation is mid-stream; telemetry is `true` (OTel spans). v1 is deliberately single-agent, `delegation: false` and `workflows: false`, because `@openai/agents`' native handoffs primitive becomes Night Owls multi-agent delegation in v1.1, not v1. `openAiAgentsEngine({ durable: true })` flips `hitl.durableResume` on (default `false`) only when the injected `StorageAdapter` persists the SDK's `RunState.toString()` snapshot (JSON, schema v1.13, genuinely cross-process-serializable) across processes. Requires Node >= 22 and peers `ai@^7` alongside `@openai/agents`/`@openai/agents-core`/`@openai/agents-extensions`/`@openai/agents-openai`. Ships a `nightOwlsPlugin` manifest (`kind: 'engine'`) so `owl install engine-openai-agents` wires `defineSwarm({ engine: openAiAgentsEngine() })`.

Install

pnpm add @nightowlsdev/engine-openai-agents

Key exports

  • openAiAgentsEngine
  • OpenAiAgentsEngine
  • OPENAI_AGENTS_ENGINE_CAPABILITIES
  • nightOwlsPlugin

Usage

engine-openai-agents.ts
import { defineSwarm } from "@nightowlsdev/core";
import { openAiAgentsEngine, OPENAI_AGENTS_ENGINE_CAPABILITIES } from "@nightowlsdev/engine-openai-agents";

// The third native engine, a governed @openai/agents run() loop. Single-agent v1: no
// delegation/workflows yet (native handoffs become multi-agent delegation in v1.1).
const swarm = defineSwarm({ agents, engine: openAiAgentsEngine() });

// Same full-governance posture as engine-mastra/engine-ai-sdk, verified, not assumed.
console.log(OPENAI_AGENTS_ENGINE_CAPABILITIES.governance.preGeneration); // true
console.log(OPENAI_AGENTS_ENGINE_CAPABILITIES.kind); // "native"