Node.js

Aeonic Node SDK

SDK for instrumenting AI agents in Express and NestJS applications. It captures request/response samples for your agent routes and integrates with AgentGuard for runtime monitoring and assessments.

Step 1. Installation

Install from npm

npm i @aeonic-agentguard/sdk-node

Requires Node.js 20+.

Step 2. Express integration

Initialize the SDK once, register expressMiddleware() once, and wrap each agent route with withAgentMiddleware().

import express from "express";
import {
  init,
  expressMiddleware,
  withAgentMiddleware,
} from "@aeonic-agentguard/sdk-node";

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

init({
  api_key: process.env.AEONIC_API_KEY!,
  app,
  service_name: "my-express-service",
});

app.use(expressMiddleware());

app.post(
  "/chat",
  withAgentMiddleware({
    name: "chat-agent",
    type: "chat",
    model: ["gpt-4o"],
    source: "manual",
  }),
  async (req, res) => {
    res.json({ reply: "Hello from Express agent" });
  },
);

app.listen(process.env.PORT ?? 3000);

Mounted routers

If agent routes live under app.use("/api/agents", router), register expressMiddleware() on that router so samples are captured reliably.

Step 3. NestJS integration

Call init() in main.ts after creating the app, register AeonicInterceptor globally, and use @WithAgent on controller methods.

main.ts

import "reflect-metadata";
import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";
import { init } from "@aeonic-agentguard/sdk-node";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  init({
    api_key: process.env.AEONIC_API_KEY!,
    app,
    service_name: "my-nest-service",
  });

  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

app.module.ts

import { Module } from "@nestjs/common";
import { APP_INTERCEPTOR } from "@nestjs/core";
import { AeonicInterceptor } from "@aeonic-agentguard/sdk-node";
import { AppController } from "./app.controller";

@Module({
  controllers: [AppController],
  providers: [
    { provide: APP_INTERCEPTOR, useClass: AeonicInterceptor },
  ],
})
export class AppModule {}

app.controller.ts

import { Controller, Post, Body } from "@nestjs/common";
import { WithAgent } from "@aeonic-agentguard/sdk-node";

@Controller()
export class AppController {
  @Post("chat")
  @WithAgent({
    name: "chat-agent",
    type: "chat",
    model: ["gpt-4o"],
  })
  async chat(@Body() body: any) {
    return { reply: "Hello from Nest agent" };
  }
}

Step 4. Environment & quick reference

Environment variables

Set these in your app's .env or deployment settings.

AEONIC_API_KEY=your-api-key
PORT=3000
# Optional — troubleshooting only:
# AEONIC_DEBUG=true

AEONIC_API_KEY — required
PORT — recommended; used when Aeonic runs assessments against your local agent
AEONIC_DEBUG — optional; more verbose logs for troubleshooting

Peer dependencies

Express: express, body-parser (or express.json())
NestJS: @nestjs/common, reflect-metadata, rxjs

Quick import reference

Express: init, expressMiddleware, withAgentMiddleware
NestJS main.ts: init
NestJS app.module.ts: AeonicInterceptor
NestJS controller: WithAgent

Step 5. Public API reference

These are the only exports you need to import from @aeonic-agentguard/sdk-node.

init(config)

One-time startup. Registers with Aeonic, emits agent inventory, and enables AgentGuard (assessments + SSE) by default.

init({
  api_key: process.env.AEONIC_API_KEY!,
  app,
  service_name: "my-service",
  capture_payloads: { max_samples: 10 },
  agentguard_enabled: true,
});

expressMiddleware()

Global Express middleware — observes responses and buffers samples for agent routes only.

withAgentMiddleware(config)

Route-level marker: name, type, model, source.

AeonicInterceptor

Global NestJS interceptor for sample collection.

@WithAgent(config)

NestJS decorator to mark a controller method as an agent endpoint.

Step 6. AgentGuard, assessments & sample collection

AgentGuard (automatic)

When init() runs with agentguard_enabled: true (default), the SDK registers with Aeonic, opens an SSE connection, and listens for assessment jobs. You do not call any additional AgentGuard APIs from your app.

Assessments

When Aeonic schedules an assessment, the SDK calls your agent routes locally with the scenario input and submits results back to Aeonic. Assessment calls include the X-Aeonic-Assessment: true header and skip sample collection.

Sample collection

Mark routes with withAgentMiddleware or @WithAgent.
Register expressMiddleware or AeonicInterceptor.
Normal traffic is buffered per agent until capture_payloads.max_samples (default 10) is reached.
The SDK then flushes a batch to Aeonic. Look for [Aeonic] Agent samples emitted successfully in logs.