Create custom tools

11 min

While Optimizely Agent Platform 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 Agent Platform 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 Agent Platform 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 Agent Platform. Think of it like a blueprint or a resume for your tool. It tells Mark 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) Mark uses to execute your tool.

Authentication requirements – Details about any authentication needed to access your tool.

If you use an Agent Platform tool creation SDK, much of the manifest creation is automated. Understanding the manifest is still helpful for debugging or ensuring that Mark 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, Agent Platform calls this endpoint to dynamically discover the tools your service provides.

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

Tool execution

After discovery, Mark 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.

Important

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

Common methods include the following:

Bearer Tokens – Agent Platform 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 Agent Platform must access user-specific data securely.

Proper authentication ensures that only authorized requests can trigger your tools, protecting your data and systems. The Agent Platform 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.

Agent Platform 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 Agent Platform's tool management service.

JavaScript (TypeScript) SDK

Installation – Install with npm. For example,

npm install @optimizely-opal/opal-tools-sdk

For installation and usage guidelines, see https://www.npmjs.com/package/@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

Note

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.

For installation and usage guidelines, see https://pypi.org/project/optimizely-opal.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

For installation and usage guidelines, see https://www.nuget.org/packages/Optimizely.Opal.Tools/.

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.

Serverless (AWS Lambda, Azure Functions, Google Cloud Functions, and Cloud Run) – All SDKs work. Prefer the one with the best tooling in your platform.

Containers (Kubernetes, Optimizely Connect Platform (OCP)) – Any SDK works. Choose based on the team's skill set.

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:

JavaScript

Python

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