---
title: Add a custom tool to Optimizely Agent Platform
slug: agent-platform/docs/add-a-custom-tool-to-agent-platform
docTags: 
createdAt: 2026-08-12T15:37:10.000Z
---

After [creating a custom tool](docId\:Hd3sW1p_TUA5w1dWF8ID9), you must add it to Optimizely Agent Platform. Your tool must be hosted on a publicly accessible URL so Agent Platform can connect to it.

You can host your tool yourself or use [Optimizely Connect Platform (OCP)](https://world.optimizely.com/products/ocp/overview/), which provides integrated hosting and seamless deployment with the Optimizely ecosystem.

## Host options

### Self-host

You can host your tool on any platform with a public URL, including [Vercel](https://vercel.com), [Netlify](https://www.netlify.com), [Amazon Web Services,](https://aws.amazon.com) [Azure](https://azure.microsoft.com/en-us/),[ Google Cloud Platform](https://cloud.google.com), or your own self-managed servers.

The only requirement is that your tool's `/discovery` endpoint is publicly accessible. See [Deploy your self-hosted custom tool](docId:1GdHO3DW4xZfN08J9ns92) for steps to add your tool to Agent Platform.

### Host with OCP

OCP provides a managed environment for hosting custom tools. It simplifies deployment, handles infrastructure, and lets you publish your tool in the Optimizely App Directory.

In OCP, Agent Platform tools are implemented as **OCP Functions**, which are event-driven services triggered by HTTP requests, usually from the Agent Platform AI Assistant. You focus on your tool's logic while OCP manages scaling and reliability.

See [Deploy your custom tool with OCP](docId:1GdHO3DW4xZfN08J9ns92) for steps.

## Deploy your self-hosted custom tool

### Initial configuration

Before adding your tool to Agent Platform, ensure it has an HTTP endpoint (commonly `/discovery`) exposed. See [Create custom tools](docId\:Hd3sW1p_TUA5w1dWF8ID9) for guidance.

### Register your tool in Optimizely Agent Platform

Complete the following steps in Agent Platform:

1. Go to **Connectors > Registries**.
2. Click **Add tool registry**.

   ![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/EBTZzuv3d1lYKKOU8eZih_add-registry.png)
3. Enter a **Registry Name**.
4. Enter your tool's discovery HTTP endpoint in the **Discovery URL** field.
5. (Optional) Enter your authentication information in the **Bearer Token (Optional)** field if you configured custom bearer token authentication or OAuth for your tool.
6. Click **Save**.

   ![click Save](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/Xyvk_EUva8U0mQ_1Z94V7_add-sample-registry.png)

Your Agent Platform tools are now discoverable and available for use within Agent Platform.

## Deploy your custom tool in OCP

### Prerequisites

- An [OCP developer account](docId\:xSq0-vrDuXX8KaA0p0WrZ).
- A configured OCP development environment, including the[ OCP Command Line Interface (CLI)](docId\:TBNojk2UclFnAMYVTs-6h).
- An initialized Git repository for your Agent Platform tool project.
- A completed Agent Platform tool. See [Create custom tools](docId\:Hd3sW1p_TUA5w1dWF8ID9) for instructions.

### Project configuration

1. Clone the [Agent Platform tool sample app GitHub repository](https://github.com/ZaiusInc/opal-tool-sample-app) or download its ZIP file.
2. Use the OCP CLI to register your application. Run the following command:

```bash
ocp app register
```

3. Enter a unique **App ID** (use snake\_case, no spaces).
4. Enter a **Display Name** for your app.
5. Select **Connect Platform** as the target product.
6. Choose whether to make the app private or share it within your organization. Choose **No** if you intend to share it within your organization.

### Configure and define your tool

1. Open `app.yml` in your project's root directory.
2. Update `meta/app_id` and `meta/display_name` to match the values you provided during registration.
3. Set `meta/vendor` (you can find your vendor ID running `ocp accounts whoami`).
4. Add `meta/summary`, `meta/support_url`, and `meta/contact_email` for the OCP App Directory listing.
5. Define your Agent Platform Tool function under the `functions` section. Adding `opal_tool: true` makes OCP display an extra section in app settings form that lets users register your app in Agent Platform.

```yaml
functions: 
  opal_tool: #A unique key for your function. 
    entry_point: OpalToolFunction #The name of the class implementing your tool. 
    description: Opal tool function #A brief description of this function.
    opal_tool: true #Lets users register your app in Opal.
```

:::Paragraph{listStyleType="disc" indent="2"}
The `entry_point` should be the class name (for instance, `OpalToolFunction`) that contains your Agent Platform Tool logic. This class must extend the `Function` class from `@zaiusinc/app-sdk` (for TypeScript and JavaScript projects).
:::

:::Paragraph{listStyleType="disc" indent="2"}
The `perform()` method within your `entry_point` class handles requests from Agent Platform, including `/discovery` for tool metadata and specific tool execution endpoints (for example, `/tools/greeting`).
:::

:::Paragraph{listStyleType="disc" indent="2"}
OCP functions support standard parameter types like string, integer, number, boolean, array, and object.
:::

6. Confirm your settings are correct before deploying your app by running the following command:

```bash
ocp app validate
```

### Custom configuration and authorization

OCP provides secure ways to handle app-specific settings and authentication.

- **Custom settings** – Define custom input fields in `forms/settings.xml` to let users configure your tool within the OCP App Directory UI.
- **Authentication**
  - **Username and password**
    - Declare input fields (for example, `email` or `api_key`) and an authorize button in `forms/settings.xml`.
    - Implement validation in the `onFormSubmit` method of `src/lifecycle/Lifecycle.ts`.
    - Access stored credentials with `storage.settings.get()`.
  - **OAuth**
    - Add an `oauth_button` to `forms/settings.xml`.
    - Implement `onAuthorizationRequest` and `onAuthorizationGrant` in your `Lifecycle` class to manage the OAuth flow.
    - Access tokens should be stored and retrieved from OCP's secure [secret storage](docId\:Fg0htEGqcx00Vcvflv-lB) using `storage.secrets.get()`.

### OCP storage and secrets

OCP offers various storage types for your app.

- [Secrets store](docId\:Fg0htEGqcx00Vcvflv-lB) – Stores sensitive information (for example, API keys or database credentials) that should not be exposed in settings forms.
- [Settings store](docId\:ASWmEhEHDdb_NVX3Fd9yV) – Backs the settings form, which is suitable for non-sensitive configuration data.
- [Key value store](docId\:wPncjf6QwaPMeEmbswmmx) – Is a general-purpose storage for simple data structures (for example, lists or sets), high throughput, up to 400 KB per record.
- [Shared key value store](docId\:Q2vOKifE429MMHRjTXK2x) – Shares common data between app components.

### Customize your app

**Dependencies**

You can add external libraries to your OCP app using your language's package manager (for example, `npm install axios` for Node.js).

**Logs and notifications**

- Use the `logger` from `@zaiusinc/app-sdk` for logging events (info, warn, debug).
  - Logs are accessible in the OCP App Directory's Troubleshooting tab or through the ocp app logs command.
  - Log levels can be changed with the `ocp app set-log-level` command.
  - See [App logs and how to troubleshoot](docId\:oybvLzTMT-Hl1-qvjyqBq) in the OCP documentation.
- Use `notifications` from `@zaiusinc/app-sdk` to send notifications to the [OCP Activity Log](docId\:GyWI81J9JQhanVqmqPlDa).

**App overview and assets**

- Customize your app's presentation in the OCP App Directory by editing `directory/overview.md`.
- Replace `assets/logo.svg` with your own icon. You should use 150 x 50 pixels for the size.

### Deploy to OCP

Before deploying, prepare your app for publication by running the following command:

```bash
ocp app prepare --bump-dev-version --publish
```

:::hint{type="info"}
**Note**

The `--bump-dev-version` flag increases the app version in `app.yml` for upgrades.
:::

Install your app to the sandbox OCP account by running the following command:

```bash
ocp directory install YOUR_APP_ID@YOUR_APP_VERSION PUBLIC_API_KEY
```

- YOUR\_APP\_ID and YOUR\_APP\_VERSION are from your `app.yml` or the `ocp app prepare` calls output.
- PUBLIC\_API\_KEY can be found in your OCP UI (**Settings > APIs**) or by running `ocp accounts whoami`.

:::hint{type="info"}
**Note**

OCP handles auto-upgrades based on semantic versioning, so installation is usually a one-time step.
:::

### Register your tool in Optimizely Agent Platform

After your OCP app is deployed and running, users can now add your app to Agent Platform.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/O7wfg1ai69S7GXTodjJpH_register-in-opal.png)

:::hint{type="info"}
**Note**

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](docId\:X5U0kKD2azV5cIdNqwGNj).
:::