feat(FR-1448): allow user to select multi agents when creating multi-node session (#4309)

resolves #4256 (FR-1448)

This PR adds support for selecting multiple agents when launching a session, available for [Backend.AI](http://Backend.AI) manager version 25.15.0 and above.

Key changes:

- Modified `AgentSelect` component to handle multiple agent selection
- Updated agent selection logic in `ResourceAllocationFormItems` to support multi-agent mode
- Added special handling for the "auto" option in multi-select mode
- Implemented proper agent_list generation in session creation payload
- Added 'multi-agents' feature detection for manager version 25.16.0+
- Changed agent default value from string to array format ['auto']
- Removed restrictions that previously disabled cluster settings when a specific agent was selected

**for testing, using test server which supports multi node session(like** **dogbowl)**
**Prior to version 25.16.0, it must behave identically to the existing version.**

how to test:

- single mode
    - Please verify that the agent_list is sent as a string[] when using multi-agents.
- multi mode
    - Please verify that the agent_list is being passed as a string array when using multi-agents.

![CleanShot 2025-09-19 at 17.15.50@2x.png](https://app.graphite.dev/user-attachments/assets/e078b5c2-c9e7-4bb0-b74a-3654f9b22503.png)

![CleanShot 2025-09-19 at 17.15.30@2x.png](https://app.graphite.dev/user-attachments/assets/adcbb2fb-388c-4f98-9d45-161b20e69550.png)

![CleanShot 2025-11-13 at 10.39.50@2x.png](https://app.graphite.com/user-attachments/assets/6dcd76fa-fcc7-4f8c-bfd0-bca9ba34c1a0.png)

**Checklist:**

- [ ] Documentation
- [x] Minium required manager version: 25.16.0
- [ ] Specific setting for review
- [ ] Minimum requirements to check during review
- [ ] Test case(s) to demonstrate the difference of before/after

Author: nowgnuesLee

react/src/components/AgentSelect.tsx

@@ -2,14 +2,14 @@ import { AgentSelectQuery } from '../__generated__/AgentSelectQuery.graphql';
 import { useBAIPaginationOptionState } from '../hooks/reactPaginationQueryOptions';
 import ResourceNumber from './ResourceNumber';
 import { useControllableValue } from 'ahooks';
-import { Select, SelectProps } from 'antd';
+import { Select, SelectProps, theme } from 'antd';
 import { filterOutEmpty, BAIFlex, mergeFilterValues } from 'backend.ai-ui';
 import _ from 'lodash';
 import React, { useDeferredValue, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import { graphql, useLazyLoadQuery } from 'react-relay';
 
-interface Props extends SelectProps {
+interface Props extends Omit<SelectProps, 'options'> {
   autoSelectDefault?: boolean;
   fetchKey?: string;
   resourceGroup?: string | null;
@@ -24,6 +24,7 @@ const AgentSelect: React.FC<Props> = ({
   const [value, setValue] = useControllableValue(selectProps);
   const [searchStr, setSearchStr] = useState<string | undefined>(undefined);
   const deferredSearchStr = useDeferredValue(searchStr);
+  const { token } = theme.useToken();
 
   const { baiPaginationOption } = useBAIPaginationOptionState({
     current: 1,
@@ -94,7 +95,13 @@ const AgentSelect: React.FC<Props> = ({
       .value();
     return {
       label: (
-        <BAIFlex direction="row" justify="between">
+        <BAIFlex
+          direction="row"
+          justify="between"
+          style={{
+            marginRight: token.marginXS,
+          }}
+        >
           {agent?.id}
           <BAIFlex direction="row" gap={'xxs'}>
             {_.map(remainingSlotsInfo, (slot, key) => {
@@ -122,19 +129,33 @@ const AgentSelect: React.FC<Props> = ({
     : undefined;
   return (
     <Select
-      onChange={(value, option) => {
-        setValue(value, option);
-      }}
       loading={searchStr !== deferredSearchStr}
       filterOption={false}
       showSearch
       searchValue={searchStr}
       onSearch={(v) => {
         setSearchStr(v);
       }}
+      options={filterOutEmpty([autoSelectIfMatch, ...agentOptions])}
+      //override props.onChange and props.value, it is handled by useControllableValue
       {...selectProps}
+      onChange={(value: unknown, option) => {
+        if (
+          selectProps.mode === 'multiple' &&
+          _.isArray(value) &&
+          _.isArray(option)
+        ) {
+          if (_.last(value) === 'auto' || value.length === 0) {
+            value = ['auto'];
+            option = _.last(option);
+          } else if (value[0] === 'auto' && value.length > 1) {
+            value = value.slice(1);
+            option = option.slice(1);
+          }
+        }
+        setValue(value, option);
+      }}
       value={value}
-      options={filterOutEmpty([autoSelectIfMatch, ...agentOptions])}
     />
   );
 };

react/src/components/AutoRefreshSwitch.tsx

@@ -1,7 +1,6 @@
 import { Switch, SwitchProps, Typography } from 'antd';
-import { BAIFlex } from 'backend.ai-ui';
+import { BAIFlex, useInterval } from 'backend.ai-ui';
 import React from 'react';
-import { useInterval } from 'src/hooks/useIntervalValue';
 
 const { Text } = Typography;
 

react/src/components/SessionFormItems/ResourceAllocationFormItems.tsx

@@ -46,7 +46,7 @@ export const RESOURCE_ALLOCATION_INITIAL_FORM_VALUES: DeepPartial<ResourceAlloca
     cluster_mode: 'single-node',
     cluster_size: 1,
     enabledAutomaticShmem: true,
-    agent: 'auto',
+    agent: ['auto'],
   };
 
 export const isMinOversMaxValue = (min: number, max: number) => {
@@ -67,7 +67,7 @@ export interface ResourceAllocationFormValue {
   cluster_size: number;
   enabledAutomaticShmem: boolean;
   allocationPreset?: string;
-  agent?: string;
+  agent?: string[] | string;
 }
 
 export type MergedResourceAllocationFormValue = ResourceAllocationFormValue &
@@ -95,6 +95,7 @@ const ResourceAllocationFormItems: React.FC<
   const { token } = theme.useToken();
 
   const baiClient = useSuspendedBackendaiClient();
+  const supportMultiAgents = baiClient.supports('multi-agents');
 
   const [{ keypairResourcePolicy, sessionLimitAndRemaining }] =
     useCurrentKeyPairResourcePolicyLazyLoadQuery();
@@ -1225,22 +1226,40 @@ const ResourceAllocationFormItems: React.FC<
         <Form.Item
           label={t('session.launcher.SelectAgent')}
           required
-          tooltip={<Trans i18nKey={'session.launcher.DescSelectAgent'} />}
+          tooltip={
+            <Trans
+              i18nKey={
+                supportMultiAgents
+                  ? 'session.launcher.DescSelectAgent'
+                  : 'session.launcher.DescSelectAgentBefore2516'
+              }
+            />
+          }
         >
           <BAIFlex gap={'xs'}>
             <Suspense>
               <Form.Item required noStyle style={{ flex: 1 }} name="agent">
                 <AgentSelect
                   resourceGroup={currentResourceGroupInForm}
                   fetchKey={agentFetchKey}
+                  mode={supportMultiAgents ? 'multiple' : undefined}
+                  labelRender={
+                    supportMultiAgents
+                      ? ({ label, value }) => {
+                          return value === 'auto' ? label : value;
+                        }
+                      : undefined
+                  }
                   onChange={(value) => {
-                    if (value !== 'auto') {
+                    if (
+                      !supportMultiAgents &&
+                      !_.isEqual(_.castArray(value), ['auto'])
+                    ) {
                       form.setFieldsValue({
                         cluster_mode: 'single-node',
                         cluster_size: 1,
                       });
                     }
-                    // TODO: set cluster mode to single node and cluster size to 1 when agent value is not "auto"
                   }}
                 ></AgentSelect>
               </Form.Item>
@@ -1286,7 +1305,12 @@ const ResourceAllocationFormItems: React.FC<
                       onChange={() => {
                         form.validateFields().catch(() => {});
                       }}
-                      disabled={getFieldValue('agent') !== 'auto'}
+                      disabled={
+                        !supportMultiAgents &&
+                        !_.isEqual(_.castArray(getFieldValue('agent')), [
+                          'auto',
+                        ])
+                      }
                     >
                       <Radio.Button value="single-node">
                         {t('session.launcher.SingleNode')}
@@ -1351,7 +1375,11 @@ const ResourceAllocationFormItems: React.FC<
                             }
                             disabled={
                               derivedClusterSizeMaxLimit === 1 ||
-                              getFieldValue('agent') !== 'auto'
+                              (!supportMultiAgents &&
+                                !_.isEqual(
+                                  _.castArray(getFieldValue('agent')),
+                                  ['auto'],
+                                ))
                             }
                             sliderProps={{
                               marks: {

react/src/components/SessionLauncherPreview.tsx

@@ -523,7 +523,7 @@ const SessionLauncherPreview: React.FC<{
             {baiClient.supports('agent-select') &&
               !baiClient?._config?.hideAgents && (
                 <Descriptions.Item label={t('session.launcher.AgentNode')}>
-                  {form.getFieldValue('agent') ||
+                  {_.castArray(form.getFieldValue('agent')).join(', ') ||
                     t('session.launcher.AutoSelect')}
                 </Descriptions.Item>
               )}

react/src/hooks/useStartSession.tsx

@@ -255,12 +255,14 @@ export const useStartSession = () => {
           // Agent selection (optional)
           ...(baiClient.supports('agent-select') &&
           !baiClient?._config?.hideAgents &&
-          values.agent !== 'auto'
+          values.agent !== undefined &&
+          !_.isEqual(values.agent, ['auto'])
             ? {
                 // Filter out undefined values
-                agent_list: [values.agent].filter(
-                  (agent): agent is string => !!agent,
-                ),
+                agent_list: _.chain(values.agent)
+                  .castArray()
+                  .filter((agent): agent is string => !!agent)
+                  .value(),
               }
             : undefined),
         },

react/src/pages/SessionLauncherPage.tsx

@@ -1276,7 +1276,7 @@ const SessionLauncherPage = () => {
                   command: undefined,
                   scheduleDate: undefined,
                 },
-                agent: 'auto', // Add the missing 'agent' property
+                agent: ['auto'], // Add the missing 'agent' property
               } as SessionLauncherFormData,
               formValue,
             );

resources/i18n/de.json

@@ -1470,7 +1470,8 @@
       "DescMemory": " <p> Der Computerspeicher ist ein temporärer Speicherbereich. </p> <p> Es enthält die Daten und Anweisungen, die die Central Processing Unit (CPU) benötigt. </p> <p> Wenn Sie eine GPU in einem Machine Learning-Workload verwenden, müssen Sie dem Arbeitsspeicher mindestens den doppelten Arbeitsspeicher der GPU zuweisen. Andernfalls erhöht sich die Leerlaufzeit der GPU, was zu einer Leistungseinbuße führt. </p>",
       "DescMultiNode": " <p> Beim Ausführen einer Sitzung werden ein verwalteter Knoten und ein oder mehrere Worker-Knoten auf mehrere physische Knoten oder virtuelle Maschinen aufgeteilt. </p>",
       "DescOpenMPOptimization": "<p>Dieser Wert legt die Anzahl der Threads fest, die für parallele Regionen verwendet werden sollen, indem er den Anfangswert der internen Steuervariablen nthreads-var festlegt.</p><p>Backend.AI setzt diesen Wert gleich der Anzahl der CPU-Kerne, was zur Folge hat, dass typische High-Performance-Computing-Workloads beschleunigt werden. Bei einigen Multi-Thread-Workloads werden jedoch mehrere Prozesse, die OpenMP verwenden, gleichzeitig verwendet, was zu einer abnormal großen Anzahl von Threads und einer erheblichen Leistungsverschlechterung führt. In diesem Fall stellen Sie diesen Wert bitte auf 1 oder 2 ein.</p>>",
-      "DescSelectAgent": "Die auf der rechten Seite des Agenten angezeigten Ressourcen stellen die tatsächliche Menge der verfügbaren Ressourcen dar. \nDerzeit ist die Agentenauswahl nur in einer Single-Node-Single-Container-Umgebung verfügbar. \nDie Standardeinstellung ist die Agentenzuteilung durch den Scheduler.",
+      "DescSelectAgent": "Die rechts neben einem Agenten angezeigten Ressourcen geben die tatsächlich verfügbaren Mengen an. Ausgewählte Agenten stellen die Kandidaten für eine Zuweisung dar; auch wenn mehrere ausgewählt sind, kann nur einem Agenten zugewiesen werden. Die Standardeinstellung ist die automatische Zuweisung durch den Scheduler.",
+      "DescSelectAgentBefore2516": "Die rechts beim Agenten angezeigten Ressourcen entsprechen der tatsächlich verfügbaren Menge. Derzeit ist die Agentenauswahl nur in einer Einzelknoten-/Einzelcontainer-Umgebung verfügbar. Standardmäßig erfolgt die Agentenzuweisung durch den Scheduler.",
       "DescSession": " <p> Eine Sitzung ist eine Einheit einer Rechenumgebung, die gemäß einer bestimmten Umgebung und Ressourcen erstellt wird. </p> <p> Wenn dieser Wert auf einen Wert größer als 1 gesetzt ist, werden mehrere Sitzungen erstellt, die dem oben genannten Ressourcensatz entsprechen. </p> <p> Wenn nicht genügend Ressourcen verfügbar sind, werden Anforderungen zum Erstellen von Sitzungen, die nicht erstellt werden können, in die Warteschlange gestellt. </p>",
       "DescSetEnv": " <p> Wenn Sie eine Standardumgebungsvariable im Container setzen und auch eine Umgebungsvariable mit demselben Namen auf der Backend.AI setzen, hat der auf der Backend.AI festgelegte Wert Vorrang. </p> <p style='color:var(--paper-red-400);'> Jeder Eingabewert wird nach dem Start des Sitzungsstarters initialisiert. <br /> Außerdem werden diese Umgebungen nur übergeben, wenn sowohl die Variable als auch der Wert nicht leer sind. </p>",
       "DescSetPreOpenPort": "Preopen Ports\" bezieht sich auf einen bestimmten <span style='color:var(--paper-red-400);'>internen Container-Port</span>, der eingehende Verbindungen von externen Geräten oder Computern auf einem Netzwerkgerät oder Computer erlaubt.",

resources/i18n/el.json

@@ -1469,7 +1469,8 @@
       "DescMemory": " <p> Η μνήμη του υπολογιστή είναι μια προσωρινή περιοχή αποθήκευσης. </p> <p> Διατηρεί τα δεδομένα και τις οδηγίες που χρειάζεται η κεντρική μονάδα επεξεργασίας (CPU). </p> <p> Όταν χρησιμοποιείτε GPU σε φόρτο εργασίας μηχανικής εκμάθησης, πρέπει να εκχωρήσετε τουλάχιστον δύο φορές τη μνήμη της GPU στη μνήμη. Διαφορετικά, ο χρόνος αδράνειας της GPU θα αυξηθεί, οδηγώντας σε ποινή απόδοσης. </p>",
       "DescMultiNode": " <p> Κατά την εκτέλεση μιας περιόδου σύνδεσης, ένας διαχειριζόμενος κόμβος και ένας ή περισσότεροι κόμβοι εργαζομένων χωρίζονται σε πολλούς φυσικούς κόμβους ή εικονικές μηχανές. </p>",
       "DescOpenMPOptimization": "<p>Αυτή η τιμή καθορίζει τον αριθμό των νημάτων που θα χρησιμοποιηθούν για τις παράλληλες περιοχές, θέτοντας την αρχική τιμή της εσωτερικής μεταβλητής ελέγχου nthreads-var.</p><p>Το Backend.AI θέτει αυτή την τιμή ίση με τον αριθμό των πυρήνων της CPU, γεγονός που έχει ως αποτέλεσμα την επιτάχυνση τυπικών υπολογιστικών φόρτων εργασίας υψηλών επιδόσεων. Ωστόσο, για ορισμένα φορτία εργασίας με πολλά νήματα, χρησιμοποιούνται ταυτόχρονα πολλές διεργασίες που χρησιμοποιούν OpenMP, με αποτέλεσμα να δημιουργείται ασυνήθιστα μεγάλος αριθμός νημάτων και σημαντική υποβάθμιση των επιδόσεων. Σε αυτή την περίπτωση, παρακαλούμε προσαρμόστε αυτή την τιμή σε 1 ή 2.</p>",
-      "DescSelectAgent": "Οι πόροι που εμφανίζονται στη δεξιά πλευρά του πράκτορα αντιπροσωπεύουν την πραγματική ποσότητα των διαθέσιμων πόρων. \nΠρος το παρόν, η επιλογή πράκτορα είναι διαθέσιμη μόνο σε περιβάλλον ενός κοντέινερ ενός κόμβου. \nΗ προεπιλεγμένη ρύθμιση είναι η κατανομή πράκτορα από τον προγραμματιστή.",
+      "DescSelectAgent": "Οι πόροι στα δεξιά του agent δείχνουν την πραγματικά διαθέσιμη ποσότητα. Οι επιλεγμένοι agent αντιπροσωπεύουν υποψήφιους προς ανάθεση — ακόμα κι αν επιλεγούν πολλοί, η ανάθεση μπορεί να γίνει μόνο σε έναν agent. Η προεπιλεγμένη ρύθμιση είναι η αυτόματη ανάθεση από τον scheduler.",
+      "DescSelectAgentBefore2516": "Οι πόροι που εμφανίζονται στη δεξιά πλευρά του agent αντιπροσωπεύουν την πραγματική ποσότητα διαθέσιμων πόρων. Προς το παρόν, η επιλογή agent είναι διαθέσιμη μόνο σε περιβάλλον με έναν κόμβο και ένα κοντέινερ. Η προεπιλεγμένη ρύθμιση είναι η ανάθεση των agent από τον scheduler.",
       "DescSession": " <p> Η περίοδος σύνδεσης είναι μια μονάδα υπολογιστικού περιβάλλοντος που δημιουργείται σύμφωνα με ένα καθορισμένο περιβάλλον και πόρους. </p> <p> Εάν αυτή η τιμή έχει οριστεί σε μια τιμή μεγαλύτερη από 1, δημιουργούνται πολλές συνεδρίες που αντιστοιχούν στον παραπάνω πόρο. </p> <p> Εάν δεν υπάρχουν αρκετοί διαθέσιμοι πόροι, τα αιτήματα για δημιουργία περιόδων σύνδεσης που δεν μπορούν να δημιουργηθούν τίθενται στην ουρά αναμονής. </p>",
       "DescSetEnv": " <p> Εάν ορίσετε μια προεπιλεγμένη μεταβλητή περιβάλλοντος στο κοντέινερ και επίσης ορίσετε μια μεταβλητή περιβάλλοντος με το ίδιο όνομα στο Backend.AI, υπερισχύει η τιμή που έχει οριστεί στο Backend.AI. </p> <p style='color:var(--paper-red-400);'> Κάθε τιμή εισόδου θα αρχικοποιηθεί μετά την έναρξη της εκκίνησης περιόδου λειτουργίας. <br /> Επίσης, αυτά τα περιβάλλοντα θα περάσουν μόνο αν και η μεταβλητή και η τιμή δεν είναι κενά. </p>",
       "DescSetPreOpenPort": "Οι \"Προανοιχτές θύρες\" αναφέρονται σε μια συγκεκριμένη <span style='color:var(--paper-red-400);'>εσωτερική θύρα εμπορευματοκιβωτίου</span> που επιτρέπει εισερχόμενες συνδέσεις από εξωτερικές συσκευές ή υπολογιστές σε μια συσκευή ή έναν υπολογιστή δικτύου.",