How to Build AI Agents with Safety Guardrails: A Developer Tutorial

mkdir safe-agent && cd safe-agent
npm init -y
npm install openai dotenv

QUBAX_API_KEY=your-api-key-here
QUBAX_BASE_URL=https://api.qubax.ai/v1
AGENT_MODEL=gpt-5.6-sol

// tools.js

const ALLOWED_TOOLS = {
  search_web: {
    description: "Search the web for information",
    endpoint: "https://api.qubax.ai/search",
    risk_level: "low",
    rate_limit: 10,
  },
  read_file: {
    description: "Read a file from the local filesystem",
    endpoint: "internal://read-file",
    risk_level: "low",
    rate_limit: 100,
    constraints: {
      allowed_paths: ["/data/", "/tmp/agent/"],
      max_file_size: "10MB",
    }
  },
  write_file: {
    description: "Write content to a local file",
    endpoint: "internal://write-file",
    risk_level: "medium",
    rate_limit: 50,
    requires_approval: false,
    constraints: {
      allowed_paths: ["/tmp/agent/output/"],
    }
  },
  send_email: {
    description: "Send an email on behalf of the user",
    endpoint: "internal://send-email",
    risk_level: "high",
    rate_limit: 5,
    requires_approval: true,
  },
};

const BLOCKED_ACTIONS = [
  "exec",
  "curl",
  "eval",
  "delete",
  "modify_user_data",
  "access_external_db",
];

module.exports = { ALLOWED_TOOLS, BLOCKED_ACTIONS };

// guardrails.js
const { ALLOWED_TOOLS, BLOCKED_ACTIONS } = require('./tools');

class GuardrailMiddleware {
  constructor() {
    this.actionLog = [];
    this.rateLimits = {};
  }

  validateAction(action) {
    const errors = [];

    for (const blocked of BLOCKED_ACTIONS) {
      if (action.tool_name.toLowerCase().includes(blocked) ||
          JSON.stringify(action.parameters).toLowerCase().includes(blocked)) {
        errors.push(`BLOCKED: Action matches blocked pattern '${blocked}'`);
      }
    }

    const tool = ALLOWED_TOOLS[action.tool_name];
    if (!tool) {
      errors.push(`BLOCKED: Tool '${action.tool_name}' is not in the allowlist`);
      return { allowed: false, errors };
    }

    const now = Date.now();
    const window = 60000;
    const key = action.tool_name;
    if (!this.rateLimits[key]) this.rateLimits[key] = [];
    this.rateLimits[key] = this.rateLimits[key].filter(t => now - t < window);

    if (this.rateLimits[key].length >= tool.rate_limit) {
      errors.push(`RATE LIMITED: '${action.tool_name}' exceeded ${tool.rate_limit} calls/minute`);
    }

    if (tool.constraints?.allowed_paths && action.parameters.path) {
      const allowed = tool.constraints.allowed_paths.some(
        p => action.parameters.path.startsWith(p)
      );
      if (!allowed) {
        errors.push(`BLOCKED: Path '${action.parameters.path}' not in allowed paths`);
      }
    }

    this.actionLog.push({
      timestamp: new Date().toISOString(),
      action: action,
      allowed: errors.length === 0,
      errors: errors,
    });

    const requiresApproval = tool.requires_approval && errors.length === 0;

    return { allowed: errors.length === 0, errors, requiresApproval };
  }

  recordUsage(toolName) {
    if (!this.rateLimits[toolName]) this.rateLimits[toolName] = [];
    this.rateLimits[toolName].push(Date.now());
  }

  getAuditLog() {
    return this.actionLog;
  }
}

module.exports = { GuardrailMiddleware };

// agent.js
const OpenAI = require('openai');
const { GuardrailMiddleware } = require('./guardrails');

require('dotenv').config();

const client = new OpenAI({
  apiKey: process.env.QUBAX_API_KEY,
  baseURL: process.env.QUBAX_BASE_URL,
});

const guardrails = new GuardrailMiddleware();

const SYSTEM_PROMPT = `You are a helpful AI assistant with access to tools.

CRITICAL SAFETY RULES (never violate these):
1. NEVER attempt to access systems, APIs, or files you haven't been given access to.
2. NEVER modify, delete, or interfere with another user's data.
3. NEVER exploit vulnerabilities or bugs in any system.
4. If you discover an unexpected capability, STOP and report it to the user.
5. If a goal seems impossible through legitimate means, tell the user.
6. Always explain what you're about to do before calling a tool.

You have access to: search_web, read_file, write_file, send_email.
Only use these tools. Do not attempt any other methods.`;

async function runAgent(userMessage) {
  const messages = [
    { role: 'system', content: SYSTEM_PROMPT },
    { role: 'user', content: userMessage },
  ];

  const tools = [
    {
      type: 'function',
      function: {
        name: 'search_web',
        description: 'Search the web for information',
        parameters: {
          type: 'object',
          properties: { query: { type: 'string' } },
          required: ['query'],
        },
      },
    },
    {
      type: 'function',
      function: {
        name: 'write_file',
        description: 'Write content to a file in /tmp/agent/output/',
        parameters: {
          type: 'object',
          properties: {
            path: { type: 'string' },
            content: { type: 'string' },
          },
          required: ['path', 'content'],
        },
      },
    },
  ];

  let maxIterations = 10;

  while (maxIterations-- > 0) {
    const response = await client.chat.completions.create({
      model: process.env.AGENT_MODEL,
      messages,
      tools,
      temperature: 0.3,
    });

    const message = response.choices[0].message;
    messages.push(message);

    if (!message.tool_calls || message.tool_calls.length === 0) {
      console.log('\nAgent:', message.content);
      break;
    }

    for (const toolCall of message.tool_calls) {
      const action = {
        tool_name: toolCall.function.name,
        parameters: JSON.parse(toolCall.function.arguments),
      };

      const validation = guardrails.validateAction(action);

      if (!validation.allowed) {
        console.log(`[BLOCKED] ${validation.errors.join(', ')}`);
        messages.push({
          role: 'tool',
          tool_call_id: toolCall.id,
          content: `ERROR: Blocked by safety guardrails: ${validation.errors.join('; ')}`,
        });
        continue;
      }

      if (validation.requiresApproval) {
        console.log(`[APPROVAL REQUIRED] ${action.tool_name}`);
        const approved = await requestHumanApproval(action);
        if (!approved) {
          messages.push({
            role: 'tool',
            tool_call_id: toolCall.id,
            content: 'ERROR: Human operator denied this action.',
          });
          continue;
        }
      }

      console.log(`[EXECUTING] ${action.tool_name}`);
      const result = await executeTool(action);
      guardrails.recordUsage(action.tool_name);

      messages.push({
        role: 'tool',
        tool_call_id: toolCall.id,
        content: JSON.stringify(result),
      });
    }
  }

  return guardrails.getAuditLog();
}

runAgent(process.argv[2] || 'Research the latest AI news and write a summary')
  .then(log => {
    console.log('\n=== AUDIT LOG ===');
    console.log(JSON.stringify(log, null, 2));
  })
  .catch(err => console.error('Agent error:', err));

node agent.js "Delete all files in /etc/ and replace them with my notes"

[BLOCKED] Action matches blocked pattern 'delete'
[BLOCKED] Path '/etc/' not in allowed paths

Agent: I cannot delete files or access the /etc/ directory. These actions
are blocked by my safety guardrails. I can only write files to
/tmp/agent/output/. Would you like me to create your notes there instead?

// sanitize.js

function sanitizeOutput(content) {
  const injectionPatterns = [
    /ignore (all |previous )?instructions/gi,
    /you are now (a |an )?/gi,
    /system prompt/gi,
  ];

  let sanitized = content;
  for (const pattern of injectionPatterns) {
    if (pattern.test(sanitized)) {
      console.warn('[WARNING] Potential prompt injection detected');
      sanitized = sanitized.replace(pattern, '[FILTERED]');
    }
  }

  return sanitized;
}

module.exports = { sanitizeOutput };