Optimizely Opal logoLearn how to create custom tools for Optimizely's AI assistant platform and deploy them to Cloudflare Workers

Introduction: What is Optimizely Opal?

Optimizely Opal represents the next generation of AI-powered marketing. As Optimizely's flagship AI assistant, Opal is built from the ground up specifically for marketing teams, integrating seamlessly across the entire Optimizely One platform. Unlike generic AI tools that require complex integrations, Optimizely Opal provides native, context-aware assistance that understands your marketing data, experiments, and content.

In 2025, Opal underwent a massive transformation, introducing agentic AI capabilities that allow marketers to automate complex workflows, generate brand-perfect content, and scale their operations infinitely. What sets Optimizely Opal apart is its flexible ecosystem of specialized tools and agents that can be extended with custom functionality.

Understanding Optimizely Opal Tools

Optimizely Opal tools are specialized software components that extend the AI assistant's capabilities. Think of them as plugins that give Opal new superpowers. The platform comes with a rich library of pre-built tools for common marketing tasks like:

  • Analyzing web pages for SEO optimization
  • Creating presentation decks from campaign data
  • Conducting keyword research
  • Generating A/B test hypotheses
  • Analyzing experiment results

But the real power comes from building custom Optimizely Opal tools tailored to your specific business needs.

It should be noted that at the time of publishing Optimizely Opal Tools are currently in beta.

Why Build Custom Tools?

While Optimizely Opal ships with dozens of built-in tools, every organization has unique workflows, data sources, and requirements. Custom tools allow you to:

  1. Integrate proprietary systems - Connect internal APIs, databases, or third-party services
  2. Automate specialized workflows - Build tools for industry-specific processes
  3. Extend data access - Give Opal access to custom data sources for better context
  4. Create competitive advantages - Build tools that differentiate your marketing operations
  5. Company specific - Any tools built are just for your organisation and 

The Optimizely Opal Tools SDK

The @optimizely-opal/opal-tools-sdk npm package provides the foundation for building custom tools. This SDK handles:

  • Tool discovery - Automatic registration with the Opal platform
  • Parameter validation - Type-safe input handling
  • Authentication - Secure communication between Opal and your tools
  • Response formatting - Standardized output formats that Opal understands

The SDK supports both JavaScript and TypeScript and there is a C# SDK too making it accessible to a wide range of developers.

Case Study: Building a NuGet Package Search Tool

To demonstrate the process, I built a custom tool that searches the Optimizely NuGet feed. This tool allows Opal to help developers find and analyze Optimizely packages during development conversations.

Project Structure

optimizely-nuget-tool/
├── src/index.ts          # Main tool implementation
├── package.json          # Dependencies and scripts  
├── tsconfig.json         # TypeScript configuration
├── wrangler.toml         # Cloudflare Worker config
└── dist/                 # Built JavaScript output

Step 1: Setting Up the Development Environment

First, I initialized a new Node.js project with TypeScript:

{
  "name": "optimizely-nuget-tool",
  "version": "1.0.0",
  "dependencies": {
    "@optimizely-opal/opal-tools-sdk": "^0.1.0-dev"
  },
  "devDependencies": {
    "@types/node": "^24.0.14",
    "typescript": "^5.8.3",
    "wrangler": "^4.24.3"
  }
}

Step 2: Implementing the Core Tool Logic

The main implementation consists of three TypeScript interfaces and two primary functions:

interface OptimizelyNugetQueryParams {
  packageName: string;
  showMore?: boolean;
}

interface NugetPackage {
  id: string;
  version: string;
  description: string;
  downloadCount?: number;
  authors?: string[];
  tags?: string[];
  projectUrl?: string;
  licenseUrl?: string;
  published?: string;
}

interface NugetSearchResult {
  data: NugetPackage[];
  totalHits: number;
}

The core function queryOptimizelyNuget() implements the business logic:

  1. Fetches the NuGet service index from https://api.nuget.optimizely.com/v3/index.json
  2. Discovers the search endpoint dynamically from the service index
  3. Executes the search query with configurable result limits
  4. Formats results as markdown for optimal display in Opal conversations

Step 3: Creating the Tool Discovery Endpoint

Every Optimizely Opal tool must implement a /discovery endpoint that describes its capabilities:

if (request.method === 'GET' && url.pathname === '/discovery') {
  const discoveryResponse = {
    functions: [
      {
        name: 'optimizely-nuget-query',
        description: 'Search for packages in the Optimizely NuGet feed',
        parameters: [
          {
            name: 'packageName',
            type: 'string',
            description: 'The name of the package to search for',
            required: true
          },
          {
            name: 'showMore',
            type: 'boolean',
            description: 'Whether to show more results (20 instead of 5)',
            required: false
          }
        ],
        endpoint: '/',
        http_method: 'POST',
        auth_requirements: []
      }
    ]
  };
}

Step 4: Handling Tool Invocation

The tool execution endpoint handles POST requests with flexible parameter parsing to accommodate different Optimizely Opal invocation patterns:

// Handle different possible parameter formats from Optimizely Opal
let params: OptimizelyNugetQueryParams;
const bodyObj = body as any;

// Check if parameters are nested under 'parameters' key
if (bodyObj.parameters) {
  params = {
    packageName: bodyObj.parameters.packageName,
    showMore: bodyObj.parameters.showMore
  };
} 
// Check if parameters are in 'arguments' key
else if (bodyObj.arguments) {
  params = {
    packageName: bodyObj.arguments.packageName,
    showMore: bodyObj.arguments.showMore
  };
}
// Check if parameters are directly in the body
else if (bodyObj.packageName) {
  params = {
    packageName: bodyObj.packageName,
    showMore: bodyObj.showMore
  };
}

Step 5: Implementing CORS and Error Handling

Optimizely Opal tools must handle CORS headers properly for web integration:

// Handle CORS preflight requests
if (request.method === 'OPTIONS') {
  return new Response(null, {
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    },
  });
}

Deploying to Cloudflare Workers

I chose Cloudflare Workers for deployment because they provide:

  • Zero cold start times - Critical for responsive AI interactions
  • Global edge distribution - Low latency from anywhere in the world
  • Generous free tier - Cost-effective for moderate usage
  • Simple deployment - Integrated with the Wrangler CLI

Cloudflare Configuration

The wrangler.toml configuration file defines deployment settings:

name = "optimizely-nuget-tool"
main = "src/index.ts"
compatibility_date = "2024-01-01"

[build]
command = "npm run build"

[env.production]
name = "optimizely-nuget-tool"

[env.staging]
name = "optimizely-nuget-tool-staging"

Deployment Process

  1. Build the TypeScript: npm run build
  2. Deploy to staging: npm run deploy:staging
  3. Test the endpoints: Verify /discovery and tool execution work
  4. Deploy to production: npm run deploy

Registering Your Tool with Optimizely Opal

Once deployed, register your custom tool in the Optimizely Opal platform:

  1. Navigate to the Opal tools section: https://opal.optimizely.com/tools
  2. Add your discovery URL: https://your-worker-domain.workers.dev/discovery
  3. Configure authentication (if required): Add bearer tokens for secure endpoints
  4. Test the integration: Verify Opal can discover and invoke your tool

Advanced Features and Best Practices

Error Handling and Logging

Implement comprehensive error handling for production reliability:

try {
  const result = await queryOptimizelyNuget(params);
  return new Response(JSON.stringify(result), {
    headers: {
      'Content-Type': 'application/json',
      'Access-Control-Allow-Origin': '*',
    },
  });
} catch (error) {
  return new Response(JSON.stringify({ 
    success: false, 
    error: 'Invalid request format',
    details: error instanceof Error ? error.message : 'Unknown error'
  }), {
    status: 400,
    headers: {
      'Content-Type': 'application/json',
      'Access-Control-Allow-Origin': '*',
    },
  });
}

Response Formatting for AI Consumption

Optimizely Opal works best with markdown-formatted responses that are easy to parse and display:

const markdownResponse = `
## 📦 NuGet Package Search Results

**Search term:** \`${packageName}\`  
**Found:** ${searchResult.totalHits} package(s)

### ${pkg.name}
**Version:** \`${pkg.version}\`  
**Description:** ${pkg.description}
**Downloads:** ${pkg.downloadCount.toLocaleString()}
`;

Health Check Endpoints

Include health check endpoints for monitoring:

if (request.method === 'GET') {
  return new Response(JSON.stringify({
    status: 'healthy',
    tool: 'optimizely-nuget-query',
    description: 'Search for packages in the Optimizely NuGet feed'
  }), {
    headers: {
      'Content-Type': 'application/json',
      'Access-Control-Allow-Origin': '*',
    },
  });
}

The result

Once implemented your tool is now accessible as part of the standard Optimizely Opal chat:

Optimizely Opal chat

The Future of Optimizely Opal Tools

The Optimizely Opal ecosystem continues to evolve rapidly. The 2025 roadmap includes:

  • Enhanced tool management - Improved discovery and versioning
  • Agent coordination - Tools that work together to solve complex problems
  • Slack and Teams integration - Opal accessible directly from Slack and Teams
  • Custom agent creation - Build specialized AI agents with your tools

Conclusion: Extending AI with Custom Capabilities

Building custom tools for Optimizely Opal opens unlimited possibilities for AI-powered marketing automation. By leveraging the Optimizely Opal Tools SDK and deploying to platforms like Cloudflare Workers, you can create powerful, scalable solutions that integrate seamlessly with your existing marketing technology stack.

The combination of Optimizely Opal's contextual AI capabilities with your custom business logic creates a force multiplier for marketing teams. Whether you're integrating proprietary data sources, automating specialized workflows, or building competitive advantages, custom tools put the power of Optimizely's AI platform to work for your unique needs.

Getting Started

Ready to build your first Optimizely Opal tool? Here's what you need:

  1. Optimizely Opal access - Ensure your organization has Opal enabled
  2. Optimizely Opal Tools (beta) enabled - Work with your Optimizely Customer Success Manager (CSM) to enable Optimizely Opal tools
  3. Development environment - Node.js, TypeScript, and the Opal Tools SDK
  4. Hosting platform - Cloudflare Workers, Vercel, or any serverless platform
  5. API or data source - Something unique for your tool to integrate with

The future of marketing automation is extensible AI, and Optimizely Opal provides the perfect platform to build it.


Comments

Recommendations for you