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:
- The model decides to call a tool — for example,
acme_tracker__search_issues— with some arguments. - Optima merges those arguments with any values the administrator has configured, and looks up the credentials the tool needs.
- Optima starts Python, passes the inputs and credentials in, and runs your script. Nothing is written to disk.
- Your script sets a variable called
result. - Optima turns
resultinto 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:
- Create the Connector on the Gateway's Connectors page. See Creating a Connector.
- Add tools and their inputs, and write each tool's Python. See Tools and Inputs and Script Reference.
- Add auth profiles if the tools sign in to another system. See Auth Profiles.
- Test each tool in the editor's debug runner, then try it in a real chat.
- Share it by exporting a
.oconfile, 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.