AI Provider and Connection Management

Before your reaktors can call AI models or connect to external services, an administrator must configure AI Providers and Connections in the platform. As a developer, you reference these by name in your code and never handle credentials directly.

• AI Providers define which LLM services are available (OpenAI, Anthropic, Azure, etc.) and which models they expose. You select a provider and model in your reaktor code via aktorAISettingProviderModel() — see LLM Calls for details and code examples.
• Connections store credentials and endpoints for external services like web search, databases, or document intelligence. You reference them by name via a connectionName parameter — see the Connection Management admin guide for setup and the Jina usage example.

If providers or connections are not yet set up for your organisation, contact your administrator or refer to the AI Provider and Connection Management chapters in the Administrator Guide.

Registering Custom Connection Types

Apps can register new connection types to integrate external services. The platform provides a type-safe API built on Zod schemas.

Define a Connection Type

import { registerConnectionType } from '@operaide/aktor';
import { z } from 'zod';

export const myServiceConnection = registerConnectionType({
    type: 'my-service',
    label: 'My Service API',
    descriptionMarkdown: '*My Service* provides data processing capabilities.',
    credentialPortalUrl: 'https://myservice.com/api-keys',
    providerIconUrl: 'https://myservice.com/favicon.ico',
    configSchema: z.object({
        apiKey: z.string().min(1).describe('API Key from My Service'),
        baseUrl: z.string().url().default('https://api.myservice.com'),
    }),
});

The registerConnectionType function accepts the following fields:

Field	Required	Description
type	Yes	Unique identifier (e.g. my-service)
label	Yes	Human-readable name shown in the admin UI
configSchema	Yes	Zod schema defining required configuration fields
descriptionMarkdown	No	Help text for administrators (supports Markdown)
credentialPortalUrl	No	Direct link to credential creation page
providerIconUrl	No	Icon displayed in the connection list
defaultConnectionName	No	Suggested default name for new connections

Schema Description Markers

You can add UI hints to your Zod schema descriptions to control how configuration fields are rendered in the admin UI:

configSchema: z.object({
    apiKey: z.string().describe('[label:API Key]Your secret API key'),
    prompt: z.string().describe('[label:System Prompt][textarea]The default system prompt'),
    certificate: z.string().describe('[file-upload]Upload your TLS certificate'),
})

Marker	Effect
[label:Custom Label]	Sets a custom display label
[textarea]	Renders the field as a multi-line text area
[file-upload]	Enables file upload for the field

Markers can be combined and must appear before the description text.

Access Connection Configuration

Use .getConnection(name) to retrieve a type-safe configuration at runtime:

import { createAktorFunction } from '@operaide/aktor';

const callMyService = createAktorFunction(
    'callMyService',
    async ({ connectionName, data }: { connectionName: string; data: string }) => {
        const config = await myServiceConnection.getConnection(connectionName);
        // config is typed as { apiKey: string; baseUrl: string }

        const response = await fetch(`${config.baseUrl}/process`, {
            method: 'POST',
            headers: {
                Authorization: `Bearer ${config.apiKey}`,
                'Content-Type': 'application/json',
            },
            body: JSON.stringify({ data }),
        });
        return response.json();
    }
);

The Zod schema validates the stored configuration at retrieval time. If the stored data does not match the schema, getConnection throws a validation error.

Connection Name Rules

Connection names must match the pattern /^[-\w/]+$/:

• Valid: jina, postgres-main, api/primary, db_production
• Invalid: jina api (space), foo@bar (special character)