Configure an AI action call in BRIX

After you create an AI action and test its performance in a test chat, set up its usage in BRIX. You can trigger AI actions:

The block and widget for calling AI actions become available after installing the BRIX AI integration solution.

Call an AI action in a business process

You can run an AI action automatically during a process. To do this, add the AI Action block to the process diagram.

For example, suppose a business process runs for every incoming email, assigning a task to an employee to respond. To make communication more effective, you can add an AI action that uses artificial intelligence to analyze email content before the agent sends a response.

The AI action receives the subject and body of the email as input data, then generates a summary and a suggested response. You can show this information in the employee's task.

To set this up:

  • Add properties to the app and process context to pass input data and display results.
  • Place the AI action block on the process diagram and configure it.

Let's look at these steps and the process setup in detail.

Step 1. Add properties for input and output data

  1. Make sure the context of the Incoming Emails app contains String (text) fields for storing the email subject and body: Name and Body.

The input properties must contain values before the process reaches the AI Action block. In our example, we use data from the app item that triggers the process, so these properties are populated beforehand. You also need to add properties to the process context to store the result of the AI action execution.

  1. Open the incoming email process in the process designer and go to the Context tab.
  2. To display the AI action result in the agent's task, add String (text) variables to the process context: Summary and Recommendations.
  3. Add the result fields to the user task form by double-clicking the task on the diagram and placing them on the Form tab.

Step 2. Configure the AI action block

To ensure the block works correctly, set up outgoing transitions and data mapping between the block and the process. Follow these steps:

  1. In process modeling mode, select the Integrations tab on the right panel and place the AI Action block on the diagram.
  2. To handle potential errors properly, add two outgoing transitions: one for standard process execution and another for errors.

In our example, both transitions lead to the Reply to Email user task, as it must be assigned in any case. If the AI action yields no result, the employee completes the task manually by reviewing the inquiry and drafting a reply.

call-ai-action-1

  1. Double-click the AI Action block to open its settings.
  2. Go to the Action Settings tab and select the required action from the list.
  3. Set up data mapping between the process and the AI action by matching properties in the displayed columns. Mapping details depend on the input format and response schema configured for the selected AI action in BRIX AI:
  • Text. One AI action field is available for mapping: input_text for input data, and output_text for the response schema. Opposite it, select a String variable from the process context that contains the input text or receives the result.
  • Arbitrary JSON. One AI action field is available for mapping: input_json for input data, and output_json for the response schema. Select a String variable from the process context that contains the JSON object or receives the result.
  • Strict JSON Schema. Fields from the AI action's JSON schema appear. Map them to variables in the process context. Data types must match.

call-ai-action-2

  1. On the Error Handling tab, enable the Interrupt option and select the transition added for error handling.
  2. Click Save.
  3. Save and publish the process.

Now, whenever the process runs, the AI action automatically executes using customer email data, and its result displays in the employee's task.

Call an AI action manually from the BRIX interface

To let users execute an AI action by clicking a button on a form or page, place the Call AI Action widget in the interface designer.

For example, an agent reading a customer inquiry on an inquiry page specifies response requirements, then clicks a button to trigger an AI action and generate an analysis. They might request a bulleted list or a ready-to-send reply. If no requirements are specified, the AI generates a brief summary by default.

To set up this AI action call from an inquiry page:

  • Add properties to pass input data and show results in the app context and form settings in  the interface designer.
  • Place the widget on the form and configure it.

Let's look at these steps in detail.

Step 1. Add properties for input and output data

  1. Open form settings for the Inquiries app and ensure its context contains fields for inquiry data: Name and Text.
  2. Switch to advanced form settings mode and open the app's view form in Interface Designer.
  3. On the Context tab, add the String (text) properties required for the AI action: Additional Analysis Requirements and Analysis Result.
  4. On the Template tab, place the new properties onto the form.
  5. Set up the Analysis Result field so users can only view its content after running the AI action. To do this, select the field on the form template, click the gear icon, and enable Read-only and Hide if Empty.

Step 2. Configure the widget to call the AI action

  1. Place the Call AI Action widget on the form.
  2. In the widget settings window, select the required AI action from the list.
  3. Configure input and output data mapping by matching action and widget properties in the displayed columns.

Mapping details depend on the input format and response schema configured for the selected AI action in BRIX AI:

  • Text. One AI action field is available for mapping: input_text for input data, and output_text for the response schema. Opposite it, select a String variable from the widget context that contains input text or receives the result.
  • Arbitrary JSON. One AI action field is available for mapping: input_json for input data, and output_json for the response schema. Select a String variable from the widget context that contains the JSON object or receives the result.
  • Strict JSON Schema. Fields from the AI action's JSON schema appear. Map them to variables in the widget context. Data types must match.

call-ai-action-3

  1. Click Save.

call-ai-action-4

  1. Click Save and Publish on the top toolbar in the interface designer.

Agents can now quickly analyze an inquiry directly on its page by entering requirements and clicking Apply.

Call an AI action from a script in BRIX

You can run an AI action from a script configured at any BRIX component level.

For example, if users need an inquiry summary on an inquiry form upon clicking a button, but the standard AI action widget design doesn't suit your layout, you can add a custom button with a custom name and icon to the Inquiries app form. Clicking this button runs a script that executes the AI action.

To set this up:

  • Add properties to pass input data and display results on the form.
  • Write a server-side script to call the AI action from BRIX AI.
  • Create a client-side script that passes input data, executes the server-side script, and displays the result on the form.
  • Bind the client-side script to the button.

Let's look at these steps in detail. In our example, we use an AI action that receives inquiry text as input and returns a text summary.

Step 1. Add properties for input data and displaying results

  1. Open form settings for the Inquiries app and ensure its context contains a property for inquiry text. In our example, this is a String (text) field named Inquiry Text (request_text).
  2. In advanced form settings mode, open the app's view form in Interface Designer.
  3. Go to the Context tab and add a String (text) property to display the AI action result: Analysis Result (analysis_result).
  4. On the Template tab, place the result field on the form.
  5. Open the field settings by selecting it on the form template and clicking the gear icon.
  6. Enable Read-only and Hide if Empty.

Step 2. Write a server-side script to call the AI action

  1. Go to the Scripts tab and select Server in the upper-right corner.
  2. Write the script:

Script for calling an AI action

// AI action execution statuses
type ActionStatus = 'Pending' | 'Success' | 'Failure' | 'Running';
 
// Supported data types
type DataType = 'JSON' | 'Text';
 
// Container for input and output data
interface DataContent<T = any> {
    type: DataType;
    data: T;
}
 
// Run details structure
interface ActionRun {
    run_id: string;
    thread_id: string;
    input: DataContent[];
    output: DataContent[];
    status: ActionStatus;
    problem: string | null;
    tracing?: {
        execution: {
            trace_id: string | null;
        };
    };
}
 
// API interfaces (Request/Response)
 
// Structure for triggering an AI action
interface StartActionRequest {
    input: DataContent[];
}
 
// Structure for AI action trigger response
interface StartActionResponse {
    model: ActionRun;
}
 
// Status check — response from GET request
interface GetActionStatusResponse extends ActionRun { }
 
// Constants for storing BRIX AI connection settings and request parameters
const CONSTANTS = {
    BASE_URL: "https://<BRIX_AI_domain>",                // BRIX AI server URL
    TOKEN: "2xd2szkub9nf2iu8fk85le7h2e9r0c99",           // Key from API Keys section in BRIX AI
    AGENT_CODE: "agn-000000",                            // Target action key from settings on API Keys tab
    API_PATHS: {
        GENERAL_FILES: "/api/pub/v1/general/files/json", // Path for generating a file in BRIX AI
        AGENT_RUNS: "/api/pub/v1/agent/runs",            // Path for running an AI action
    },
    HEADERS: {                                           // Header data
        X_TOKEN: "x-token",
        CONTENT_TYPE: "Content-Type",
        APPLICATION_JSON: "application/json",
        AUTHORIZATION: "Authorization"
    },
    AGENT_RUN_STATUS: {                                  // AI action execution statuses
        SUCCESS: "SUCCESS",
        PENDING: "PENDING",
        FAILURE: "FAILURE",
        RUNNING: "RUNNING",
    },
    HTTP_METHOD: {                                       // Used HTTP methods
        POST: "POST",
        GET: "GET"
    }
};
 
// Run AI action and pass input data
// Returns run ID
async function cortexCall(userData: string): Promise<string> {
    const inputs: DataContent[] = await buildAgentInputs(userData);
    const requestBody: StartActionRequest = { input: inputs };
 
    const url = `${CONSTANTS.BASE_URL}${CONSTANTS.API_PATHS.AGENT_RUNS}?f_agent_external_id=${CONSTANTS.AGENT_CODE}`;
    const response = await fetch(url, {
        method: CONSTANTS.HTTP_METHOD.POST,
        headers: {
            [CONSTANTS.HEADERS.X_TOKEN]: CONSTANTS.TOKEN,
            [CONSTANTS.HEADERS.CONTENT_TYPE]: CONSTANTS.HEADERS.APPLICATION_JSON
        },
        body: JSON.stringify(requestBody)
    });
 
    if (!response.ok) {
        throw new Error(`[Error:callAiAction:Ошибка запроса]: ${response.status} ${response.statusText}`);
    }
 
    const dataResponse = await response.json() as StartActionResponse;
    if (dataResponse.model.problem) {
        throw new Error(`[Error:callAiAction]: error requesting agents: ${JSON.stringify(dataResponse.model.problem)}`);
    }
 
    return dataResponse.model.run_id;
}
 
// Build request body for triggering an AI action based on input data
async function buildAgentInputs(inputData: any): Promise<DataContent[]> {
    const inputs: DataContent[] = [];
    const jsonData: any = {};
 
    // Process input data for use in BRIX AI
    jsonData.request_text = processPrimitiveField(inputData);
 
    if (Object.keys(jsonData).length > 0) {
        inputs.push({
            type: "JSON",
            data: jsonData
        });
    }
 
    return inputs;
}
 
// Process primitive data types
function processPrimitiveField(bindData: any): any {
    switch (typeof bindData) {
        case "number": return Number(bindData);
        case "boolean": return Boolean(bindData);
        case "undefined": return null;
        case "string":
        default: return bindData;
    }
}
 
// Check AI action execution status
async function checkStatusAiAction(RunId: string): Promise<GetActionStatusResponse> {
    const url = `${CONSTANTS.BASE_URL}${CONSTANTS.API_PATHS.AGENT_RUNS}/${RunId}`;
    const response = await fetch(url, {
        method: CONSTANTS.HTTP_METHOD.GET,
        headers: { [CONSTANTS.HEADERS.X_TOKEN]: CONSTANTS.TOKEN }
    });
 
    if (!response.ok) {
        throw new Error(`${response.status} ${response.statusText} ${await response.text()}`);
    }
 
    const checkResult = await response.json() as GetActionStatusResponse;
 
    return checkResult;
}
 
// Poll AI action status and wait for execution results
async function waitForResult(RunId: string, maxAttempts = 60, interval = 2000): Promise<DataContent[]> {
    for (let i = 0; i < maxAttempts; i++) {
        const res = await checkStatusAiAction(RunId);
 
        if (res.problem) {
            throw new Error(`[Error:waitForResult:Error checking status]: ${JSON.stringify(res.problem)}`);
        }
        if (res.status.toUpperCase() === CONSTANTS.AGENT_RUN_STATUS.SUCCESS) {
            return res.output;
        }
        await new Promise(resolve => setTimeout(resolve, interval));
    }
    throw new Error("[Error:waitForResult]: Timeout exceeded");
}
 
// Main function to execute an AI action
async function runAiAction(): Promise<string> {
   const id = await cortexCall(Context.data.request_text); // Run AI action
   const output = await waitForResult(id); // Store AI action response
      ViewContext.data.analysis_result = output;
}

Step 3. Write a client-side script to run the server-side script

  1. Go to the Scripts tab and select Client in the upper-right corner.
  2. Write a function that calls the server script to launch the AI action:

async function runRequestAnalysis(): Promise<void> {
   await Server.rpc.runAiAction();
}

Step 4. Set up an AI action on button click

  1. On the Template tab, place a Button widget on the form.
  2. In the settings window that opens, enter the name and icon. In the Action type field, select Script and specify the function created in step 3.

call-ai-action-5

  1. Save the widget settings.
  2. On the top panel of the interface designer, click Save and Publish.

Now, if an inquiry is lengthy, an employee can click the button to generate a summary. Once the text is processed, they will see the Analysis result field  (analysis_result), which displays the response from the AI action.

ai-action-calibration.html cortex-connect-tools.html