Deployment Guide - AI Agents House SDK

This guide covers best practices and strategies for deploying your AI agent application with the AI Agents House SDK integrated. Proper deployment ensures that monitoring is reliable, performant, and secure in your production environment.

Pre-deployment Checklist

Before deploying to production, ensure you have:

Finalized Configuration: Your AgentMonitor configuration is set for production (e.g., appropriate batchSize, flushInterval, and logLevel).
Tested Thoroughly: Your application has been tested against a staging environment. See our Testing Guide for comprehensive strategies.
Managed Secrets: Your AGENT_GOVERNANCE_API_KEY and other secrets are managed securely and are not hardcoded.

Environment Configuration

It is critical to manage different configurations for your development, staging, and production environments. The most secure and flexible way to do this is with environment variables.

// config/monitor.js
import { AgentMonitor } from '@agent-governance/node';

function initializeMonitor() {
  const environment = process.env.NODE_ENV || 'development';

  const config = {
    apiKey: process.env.AGENT_GOVERNANCE_API_KEY,
    organizationId: process.env.AGENT_GOVERNANCE_ORG_ID,
    environment: environment,
  };

  if (environment === 'production') {
    // Production-optimized settings
    Object.assign(config, {
      enableLogging: false,
      logLevel: 'error',
      batchSize: 500,
      flushInterval: 15000, // 15 seconds
      retryAttempts: 5,
      retryDelay: 2000
    });
  } else {
    // Development/Staging settings
    Object.assign(config, {
      enableLogging: true,
      logLevel: 'debug',
      batchSize: 10,
      flushInterval: 2000 // 2 seconds
    });
  }

  return new AgentMonitor(config);
}

module.exports = { initializeMonitor };
<Warning>Never commit API keys or other secrets to your version control system. Use environment variables or a secret management service (like AWS Secrets Manager, HashiCorp Vault, or Doppler) to handle sensitive credentials.</Warning>Graceful ShutdownOne of the most critical aspects of deploying an application with the SDK is ensuring a graceful shutdown. The SDK buffers events in memory and sends them in batches. If your application process exits abruptly, any events still in the buffer will be lost.You must call await monitor.shutdown() to flush any remaining events before your process terminates.Example: Node.js HTTP Serverconst { initializeMonitor } = require('./config/monitor');
import http from 'http';

const monitor = initializeMonitor();
const server = http.createServer((req, res) => {
  // Your application logic here
  monitor.trackUserMessage('web-agent', 'session-123', 'Request received');
  res.end('Hello World!');
});

const PORT = process.env.PORT || 3000;
server.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

async function gracefulShutdown() {
  console.log('Shutting down gracefully...');
  server.close(async () => {
    console.log('HTTP server closed.');
    try {
      await monitor.shutdown();
      console.log('Agent monitor flushed and shut down.');
      process.exit(0);
    } catch (error) {
      console.error('Error during monitor shutdown:', error);
      process.exit(1);
    }
  });
}

// Listen for termination signals
process.on('SIGTERM', gracefulShutdown);
process.on('SIGINT', gracefulShutdown);

Deployment Strategies

The AI Agents House SDK is a standard Node.js library and can be deployed in any environment that supports Node.js.

Serverless (AWS Lambda, Vercel)

In a serverless environment, the execution context can be frozen or terminated after a request is handled. This makes graceful shutdown even more important.Key Considerations:

shutdown() is essential: Because serverless functions can terminate at any time, you must flush() or shutdown() the monitor at the end of each invocation that tracks events.
Connection Reuse: Serverless platforms often reuse execution contexts. You can initialize the monitor outside of your handler function to reuse the instance across invocations, but be mindful of flushing data.

Example: AWS Lambda Handler

import { initializeMonitor } from './config/monitor';
const monitor = initializeMonitor(); // Initialize outside handler

exports.handler = async (event) => {
const sessionId = event.requestContext.requestId;
monitor.trackConversationStart('lambda-agent', sessionId);
// ... your logic ...
monitor.trackAgentResponse('lambda-agent', sessionId, 'Processed successfully.');

// Flush events at the end of the invocation
await monitor.flush();

return {
statusCode: 200,
body: JSON.stringify({ message: 'Success' }),
};
};

Containers (Docker, Kubernetes)

Deploying with containers is a robust way to manage your application and its dependencies.Key Considerations:

Dockerfile: Ensure your Dockerfile correctly installs dependencies (npm ci --only=production) and copies necessary files.
Environment Variables: Pass your API key and other configurations to the container using environment variables (-e flag in Docker or env in Kubernetes manifests).
Health Checks: Configure Kubernetes liveness and readiness probes for your application.
Graceful Shutdown: Kubernetes sends a SIGTERM signal to pods before termination. Your application must handle this signal to call monitor.shutdown().

Example: Dockerfile

FROM node:18-alpine

WORKDIR /usr/src/app

COPY package*.json ./
RUN npm ci --only=production

COPY . .

# Expose your application's port
EXPOSE 3000

# Set environment variables in your deployment configuration
# ENV AGENT_GOVERNANCE_API_KEY=your_key
# ENV AGENT_GOVERNANCE_ORG_ID=your_org_id
# ENV NODE_ENV=production

CMD [ "node", "server.js" ]

Traditional Servers (EC2, Virtual Machines)

When deploying on a traditional virtual machine, using a process manager like PM2 is highly recommended.Key Considerations:

Process Manager: Use PM2 to manage your Node.js process, handle restarts, and manage logs.
Graceful Shutdown with PM2: PM2 sends SIGINT to your application, which you can catch to trigger monitor.shutdown().
Environment Configuration: Use a .env file or the OS’s environment to manage secrets.

Example: PM2 Ecosystem File

// ecosystem.config.js
module.exports = {
apps: [{
name: 'ai-agent-app',
script: 'server.js',
instances: 'max',
exec_mode: 'cluster',
env_production: {
NODE_ENV: 'production',
AGENT_GOVERNANCE_API_KEY: 'your_prod_key',
AGENT_GOVERNANCE_ORG_ID: 'your_prod_org'
}
}]
};

​Pre-deployment Checklist

​Environment Configuration

​Deployment Strategies

Pre-deployment Checklist

Environment Configuration

Deployment Strategies