Skip to content

Building Connectors

An Optima Connector is a named set of tools that an AI model can call. Each tool is a short Python script. When the model calls a tool, Optima will start a fresh Python process, hand it the arguments, run your script, and give the model whatever the script returns.

You can build your own Connectors to give the AI access to your own systems and data. This section is for people who write Connectors. To install and set up Connectors someone else has built, see Connectors Overview.

What A Connector Contains

A Connector is made up of the following parts:

Part What it is
Details Name, description, version, author, licence, tags, and where the Connector runs
Tools One or more Python scripts. Each has its own inputs, description for the model, and timeout
Auth profiles Optional. Named credentials, such as an API key or an OAuth sign-in, that tools use to reach another system. The values are never part of the Connector itself
Python dependencies Optional. Extra packages from PyPI, pinned to exact versions

How A Tool Call Works

Each time the model calls a tool, the following happens:

  1. The model decides to call a tool — for example, acme_tracker__search_issues — with some arguments.
  2. Optima merges those arguments with any values the administrator has configured, and looks up the credentials the tool needs.
  3. Optima starts Python, passes the inputs and credentials in, and runs your script. Nothing is written to disk.
  4. Your script sets a variable called result.
  5. Optima turns result into JSON, and that is what the model reads.

The details are in Script Reference.

Where A Connector Runs

When you create a Connector you choose where its tools run. All the tools in a Connector run in the same place.

Server Client
Runs on The Gateway The person's own computer, inside the Optima Chat desktop app
Can reach Whatever the Gateway can reach: web APIs, and systems on its own network The person's files, folders, local tools and local network
Sign-in Static credentials and OAuth Static credentials only
Works in Desktop chat, web chat and the API The desktop app only, once the person has installed the Connector runtime

As a rule, if a Connector works with the person's own computer — files, the clipboard, local programs, a service on localhost — make it Client. If it talks to a web API, make it Server. A Server tool that "reads a file" reads the Gateway's disk, which is rarely what anyone wants.

If you need both kinds of tool, build two Connectors. Client Connectors are what Desktop Connectors are.

From Idea To Installed

Building a Connector follows these steps:

  1. Create the Connector on the Gateway's Connectors page. See Creating a Connector.
  2. Add tools and their inputs, and write each tool's Python. See Tools and Inputs and Script Reference.
  3. Add auth profiles if the tools sign in to another system. See Auth Profiles.
  4. Test each tool in the editor's debug runner, then try it in a real chat.
  5. Share it by exporting a .ocon file, which another Gateway can import. See Testing and Sharing.

A Connector is live on your Gateway as soon as it has a tool. Until you are ready, switch it Off so that nobody's chats are offered half-built tools. See Switching a connector off while you work.

Before you share a Connector, go through the Checklist.

Who Can Do What

Building and managing Connectors needs the following permissions:

To You need
Create, edit, import, export and delete Optima Connectors, and enter their credentials Optima Connectors, and Access Gateway
Install the Python packages a Connector declares Connector Dependencies
Turn on package installs, and choose which environment variables every tool sees Connector Dependencies
Change the Gateway's default and maximum tool timeouts Settings
Give a Connector to an Assistant Permission to manage that Assistant. See Assistants

Optima Connectors is not given to new User accounts automatically: tick it for each person who builds Connectors. Admin accounts always have it. Someone without it who opens the editor will see "You don't have permission to edit connectors." See Users and Permissions.

Warning

A Connector's tools run Python on the Gateway's machine, as the Gateway's own service account. Give Optima Connectors only to people you would trust with that.

Publishing On The Marketplace

You cannot publish to the Optima connector marketplace from the Gateway. To have a Connector listed there, contact Parker Software.