Create custom tools

  • Updated

While Optimizely Opal includes a powerful set of system tools, every business has unique needs, proprietary systems, and specific workflows that generic solutions cannot fully address. Custom tools let you extend Opal to help with your organization's specific use cases and needs.

How custom tools work

Before you start building custom tools, you should understand the fundamental concepts of how Opal discovers, manages, and interacts with custom tools. The following concepts form the foundation of the tool integration. 

Tool manifest

The tool manifest is a structured declaration (often a JSON object) that describes your tool to Opal. Think of it like a blueprint or a resume for your tool. It tells Opal what your tool does and how to use it. 

The tool manifest includes the following:

  • Name and description – Human-readable label and summary of your tool.
  • Parameters – The inputs your tool expects, including name, data type (string, number, boolean, array, or object), description, and whether they are required.
  • Execution details – Information about the HTTP endpoint (URL) and method (GET or POST) Opal uses to execute your tool.
  • Authentication requirements – Details about any authentication needed to access your tool.

If you use an Opal tool creation SDK, much of the manifest creation is automated. Understanding the manifest is still helpful for debugging or ensuring that Opal can correctly discover and execute your tool.

Discovery endpoints

The discovery endpoint is a specific HTTP endpoint (commonly /discovery) that returns your tool manifest and is exposed by your tool service. When you register a custom tool, Opal calls this endpoint to dynamically discover the tools your service provides.

If this endpoint is inaccessible, returns errors, or provides a malformed manifest, Opal is not able to find or use your tools. The Opal tool creation SDKs automate the creation and management of this endpoint.

Tool execution

After discovery, Opal can run your tool by sending a request to its execution endpoint. Typically, this is a POST request with a JSON body containing the input parameters.

Your tool processes the request, performs the task, and sends back a response, usually as JSON. Understanding this request and response flow is key to building reliable tools.

This is the actual "work" phase. Understanding the request and response format is crucial for implementing your tool's core logic.

Authentication

Authentication verifies that the request to your tool is coming from a trusted source. This protects your data and systems from unauthorized access.

Opal supports only Opti ID for tool authentication. Optimizely is working on releasing support for additional providers.

Common methods include the following:

  • Bearer Tokens – Opal sends a secret token in the Authorization header (for example, Bearer YOUR_SECRET_TOKEN), and your tool validates it.
  • OAuth flows – This is used for integrations with third-party services (for example, Google or Salesforce), where Opal must access user-specific data securely.

Proper authentication ensures that only authorized requests can trigger your tools, protecting your data and systems. The Opal tool creation SDKs provide helpers to simplify the implementation of these security measures.

Configuration

Tools often require environment variables, API keys, or database connection strings to run correctly in different environments like development, staging, and production.

Avoid hardcoding sensitive information. Use configuration management so you can deploy the same tool across environments safely and securely.

Opal tool creation SDKs

Optimizely provides SDKs for popular programming languages, making it easier to build custom tools. Each SDK manages discovery, execution, and communication with Opal's tool management service.

JavaScript (TypeScript) SDK

  • Installation – Install with npm. For example, 

    npm install @optimizely-opal/opal-tools-sdk
  • Best for – Web-based tools, UI extensions, and Node.js or browser-based workflows. Great for high-concurrency network operations.
  • Key features
    • Type definitions for strong typing and better developer experience.
    • Express.js middleware for handling discovery and execution endpoints.
    • Decorators like @tool() for clean, readable tool definitions.
    • Built-in parameter validation.
    • Authentication helpers.

Python SDK

  • Installation – Install with pip. For example,

    pip install optimizely-opal.opal-tools-sdk
    The package name you install with pip is different from the module name you import in Python. Install with pip install optimizely-opal.opal-tools-sdk, but import with import opal_tools_sdk.
  • Best for – Backend automation, data processing, machine learning, and analytical tasks.
  • Key features
    • Decorators like @tool() to define tools.
    • Automatic creation of the /discovery endpoint.
    • Built-in parameter validation with Python type hints.
    • FastAPI integration for building APIs with Python 3.7+.
    • Authentication helpers.

C# SDK

  • Installation – Install with NuGet. For example,

    Install-Package OptimizelyOpal.OpalToolsSDK
  • Best for – Integrating with existing .NET applications and enterprise systems, especially in Microsoft-focused organizations.
  • Key features
    • C# attributes like [Tool] and [RequiresAuth] for defining tools.
    • ASP.NET Core integration for APIs and services.
    • Advanced parameter validation.
    • Built-in dependency injection support..

How to choose an SDK

Consider the following when deciding which SDK to use:

  • Team expertise and tech stack – Prefer the SDK your team already knows to reduce ramp-up time and simplify maintenance.
  • Performance needs – Match the language to the workload.
    • C# – Choose for high-performance, low-latency backend services.
    • Python – Choose for data-heavy processing, machine learning, and analytics.
    • JavaScript – Choose for I/O-bound work like concurrent web or API requests.
  • Tool type – Align the SDK with what the tool primarily does.
    • Backend automation or workflows – Use C# or Python.
    • Data processing or machine learning – Use Python (for example, Pandas, NumPy, Scikit-learn, TensorFlow, PyTorch).
    • Web or browser-based integrations – Use JavaScript.
  • External integrations – Pick what fits the systems you connect to.
    • C# – Best for the Microsoft ecosystem (for instance, Azure or SQL Server).
    • Python – Strong community libraries for cloud and data services.
    • JavaScript – Excellent support for web APIs.
  • Deployment environment – Choose what fits your hosting model.

Next steps

When you have chosen an SDK, see the following SDK documentation for step-by-step instructions on usage and create your custom tool:

After creating your custom tool, see Add a custom tool to Optimizely Opal.

If you use Opti ID, administrators can turn off generative AI in the Opti ID Admin Center. See Turn generative AI off across Optimizely applications.