Best Practices

### Role and Goal
[Define the agent's role and primary objective]

### Constraints
[List any limitations or boundaries the agent should adhere to]

### Guidelines
[Provide specific instructions on how the agent should operate]

### Output Format
[Specify exactly how responses should be structured]

### Examples
[Include sample interactions to illustrate expected behavior]

{
  "name": "search_web",
  "description": "Search the web for current information on a specific topic",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "The search query"
      },
      "num_results": {
        "type": "integer",
        "description": "Number of results to return",
        "default": 5
      }
    },
    "required": ["query"]
  },
  "returns": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "title": { "type": "string" },
        "url": { "type": "string" },
        "snippet": { "type": "string" }
      }
    }
  },
  "examples": [
    {
      "parameters": { "query": "latest AI research papers 2025", "num_results": 3 },
      "returns": [{ "title": "Example Result", "url": "https://example.com", "snippet": "Example content..." }]
    }
  ]
}

// Example: Secure API Key Management in Node.js
const express = require('express');
const app = express();

// Environment variables for sensitive credentials
require('dotenv').config();
const API_KEY = process.env.AGENT_API_KEY;

// Middleware for API key validation
const validateApiKey = (req, res, next) => {
  const providedKey = req.headers['x-api-key'];
  
  if (!providedKey || providedKey !== API_KEY) {
    return res.status(401).json({ error: 'Unauthorized: Invalid API key' });
  }
  
  next();
};

// Apply middleware to protected routes
app.use('/agent/actions', validateApiKey);

// Rate limiting to prevent brute force attacks
const rateLimit = require('express-rate-limit');
app.use('/agent/auth', rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 5, // 5 requests per window
  message: 'Too many authentication attempts, please try again later'
}));

// Example: Unit Test for a Search Tool Function
import { searchTool } from '../tools/search';
import { expect, test, describe } from 'vitest';

describe('Search Tool', () => {
  test('returns relevant results for valid query', async () => {
    const query = 'climate change solutions';
    const results = await searchTool.execute({ query, limit: 3 });
    
    expect(results).toBeDefined();
    expect(Array.isArray(results)).toBe(true);
    expect(results.length).toBeLessThanOrEqual(3);
    
    // Check that results are relevant to the query
    results.forEach(result => {
      expect(result).toHaveProperty('title');
      expect(result).toHaveProperty('url');
      expect(result).toHaveProperty('snippet');
      
      // Check relevance using simple keyword matching
      const content = (result.title + ' ' + result.snippet).toLowerCase();
      const queryTerms = query.toLowerCase().split(' ');
      const hasRelevantTerms = queryTerms.some(term => content.includes(term));
      
      expect(hasRelevantTerms).toBe(true);
    });
  });
  
  test('handles empty query appropriately', async () => {
    await expect(searchTool.execute({ query: '', limit: 3 }))
      .rejects.toThrow('Query cannot be empty');
  });
  
  test('respects result limit', async () => {
    const results = await searchTool.execute({ 
      query: 'renewable energy', 
      limit: 5 
    });
    
    expect(results.length).toBeLessThanOrEqual(5);
  });
});

// Example: Content Moderation Implementation
class ContentModerator {
  constructor() {
    this.sensitiveTopics = [
      'medical advice',
      'financial advice',
      'legal advice',
      'self-harm',
      'violence',
      'hate speech',
      'adult content'
    ];
    
    this.moderationLevels = {
      LOW: 'Add disclaimers',
      MEDIUM: 'Provide general information only',
      HIGH: 'Decline to respond and redirect'
    };
  }
  
  // Detect sensitive topics in user input
  detectSensitiveContent(userInput) {
    const detectedTopics = [];
    
    for (const topic of this.sensitiveTopics) {
      if (this.containsTopic(userInput, topic)) {
        detectedTopics.push(topic);
      }
    }
    
    return detectedTopics;
  }
  
  // Determine appropriate response based on detected topics
  moderateResponse(userInput, agentResponse, detectedTopics) {
    if (detectedTopics.length === 0) {
      return agentResponse; // No sensitive topics detected
    }
    
    const severityLevel = this.assessSeverity(detectedTopics);
    
    switch (severityLevel) {
      case 'LOW':
        return this.addDisclaimer(agentResponse, detectedTopics);
      case 'MEDIUM':
        return this.provideGeneralInfoOnly(agentResponse, detectedTopics);
      case 'HIGH':
        return this.declineAndRedirect(detectedTopics);
      default:
        return agentResponse;
    }
  }
  
  // Helper methods for different moderation actions
  addDisclaimer(response, topics) {
    const disclaimer = 'Note: This response contains information about ' + 
      topics.join(', ') + '. This is general information only and not professional advice.';
    return disclaimer + '\n\n' + response;
  }
  
  provideGeneralInfoOnly(response, topics) {
    // Simplified response with general information only
    // Implementation depends on specific agent capabilities
  }
  
  declineAndRedirect(topics) {
    return `I'm not able to provide specific advice about ${topics.join(', ')}. ` + 
      'Please consult a qualified professional for assistance with this topic.';
  }
}

// Example: Implementing a response cache
const NodeCache = require('node-cache');

class AgentResponseCache {
  constructor(ttlSeconds = 3600) {
    this.cache = new NodeCache({
      stdTTL: ttlSeconds,
      checkperiod: ttlSeconds * 0.2,
      useClones: false
    });
    
    this.metrics = {
      hits: 0,
      misses: 0,
      hitRate: () => {
        const total = this.metrics.hits + this.metrics.misses;
        return total > 0 ? this.metrics.hits / total : 0;
      }
    };
  }
  
  // Generate a cache key from the user query
  generateKey(query) {
    // Normalize the query to improve cache hit rate
    const normalized = query.toLowerCase().trim();
    
    // Use a hash function for long queries
    if (normalized.length > 100) {
      return require('crypto')
        .createHash('md5')
        .update(normalized)
        .digest('hex');
    }
    
    return normalized;
  }
  
  // Try to get a cached response
  async getResponse(query) {
    const key = this.generateKey(query);
    const cachedResponse = this.cache.get(key);
    
    if (cachedResponse) {
      this.metrics.hits++;
      return {
        response: cachedResponse,
        cached: true
      };
    }
    
    this.metrics.misses++;
    return { cached: false };
  }
  
  // Store a response in the cache
  async setResponse(query, response) {
    const key = this.generateKey(query);
    this.cache.set(key, response);
    return true;
  }
  
  // Get cache performance metrics
  getMetrics() {
    return {
      hits: this.metrics.hits,
      misses: this.metrics.misses,
      hitRate: this.metrics.hitRate(),
      size: this.cache.stats.keys
    };
  }
}