> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiagentshouse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployment Guide

> Best practices for deploying applications using the AI Agents House SDK to production environments.

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](/guides/testing) 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.

```javascript theme={null}
// 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.

<AccordionGroup>
  <Accordion title="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**

    ```javascript theme={null}
    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' }),
    };
    };
    ```
  </Accordion>

  <Accordion title="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**

    ```dockerfile theme={null}
    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" ]
    ```
  </Accordion>

  <Accordion title="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**

    ```javascript theme={null}
    // 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'
    }
    }]
    };
    ```
  </Accordion>
</AccordionGroup>