✨Feat: Agent supports model selection. (#3313)

* ✨Feat: Agent supports model selection.

* ✨Feat: Agent supports model selection.
[Specification Details]
1. The northbound interface now supports passing in `model_id`, incremental SQL addition is implemented, and test files have been added.

* ✨Feat: Agent supports model selection.
[Specification Details]
1. Conflict resolve.

* ✨Feat: Agent supports model selection.
[Specification Details]
1. Frontend Build Fixes.

* ✨Feat: Agent supports model selection.
[Specification Details]
1. Update sql.

Author: YehongPan

backend/apps/northbound_app.py

@@ -206,6 +206,13 @@ async def run_chat(
                     "or a list of attachment objects with full metadata.",
         examples=[["s3://nexent/attachments/user123/20260609_report.pdf"]],
     ),
+    model_id: Optional[int] = Body(
+        None,
+        embed=True,
+        description="Optional model ID to use for this run. Overrides the agent's default "
+                    "model so different models can be used for Q&A on the same agent.",
+        examples=[123],
+    ),
     meta_data: Optional[Dict[str, Any]] = Body(
         None,
         embed=True,
@@ -255,6 +262,7 @@ async def run_chat(
             attachments=attachments,
             meta_data=meta_data,
             tool_params=tool_params,
+            model_id=model_id,
             idempotency_key=idempotency_key,
         )
     except LimitExceededError as e:

backend/consts/model.py

@@ -540,8 +540,7 @@ class AgentInfoRequest(BaseModel):
     description: Optional[str] = None
     business_description: Optional[str] = None
     author: Optional[str] = None
-    model_name: Optional[str] = None
-    model_id: Optional[int] = None
+    model_ids: Optional[List[int]] = None
     max_steps: Optional[int] = Field(default=None, ge=1, le=30)
     requested_output_tokens: Optional[int] = Field(default=None, gt=0)
     provide_run_summary: Optional[bool] = None
@@ -652,8 +651,8 @@ class ExportAndImportAgentInfo(BaseModel):
     enabled: bool
     tools: List[ToolConfig]
     managed_agents: List[int]
-    model_id: Optional[int] = None
-    model_name: Optional[str] = None
+    model_ids: Optional[List[int]] = None
+    model_names: Optional[List[str]] = None
     business_logic_model_id: Optional[int] = None
     business_logic_model_name: Optional[str] = None
     skill_names: Optional[List[str]] = None

backend/database/agent_db.py

@@ -220,8 +220,6 @@ def create_agent(agent_info, tenant_id: str, user_id: str):
             "display_name": new_agent.display_name,
             "description": new_agent.description,
             "author": new_agent.author,
-            "model_id": new_agent.model_id,
-            "model_name": new_agent.model_name,
             "max_steps": new_agent.max_steps,
             "duty_prompt": new_agent.duty_prompt,
             "constraint_prompt": new_agent.constraint_prompt,

backend/database/db_models.py

@@ -438,10 +438,8 @@ class AgentInfo(TableBase):
     display_name = Column(String(100), doc="Agent display name")
     description = Column(Text, doc="Description")
     author = Column(String(100), doc="Agent author")
-    model_name = Column(
-        String(100), doc="[DEPRECATED] Name of the model used, use model_id instead")
-    model_id = Column(
-        Integer, doc="Model ID, foreign key reference to model_record_t.model_id")
+    model_ids = Column(
+        ARRAY(Integer), doc="List of model IDs, foreign key references to model_record_t.model_id, max 5 models")
     max_steps = Column(Integer, doc="Maximum number of steps")
     duty_prompt = Column(Text, doc="Duty prompt content")
     constraint_prompt = Column(Text, doc="Constraint prompt content")

backend/services/agent_service.py

@@ -303,12 +303,16 @@ def get_version_detail_impl(
     # Add enabled skills to result
     result['skills'] = [s for s in skills_snapshot if s.get('enabled', True)]
 
-    # Get model name from model_id
-    if result.get('model_id') is not None and result['model_id'] != 0:
-        model_info = get_model_by_model_id(result['model_id'])
-        result['model_name'] = model_info.get('display_name', None) if model_info else None
-    else:
-        result['model_name'] = None
+    # Get model names from model_ids array
+    snapshot_model_ids = result.get("model_ids") or []
+    snapshot_model_names: List[str] = []
+    for mid in snapshot_model_ids:
+        mid_info = get_model_by_model_id(mid)
+        if mid_info and mid_info.get("display_name"):
+            snapshot_model_names.append(mid_info["display_name"])
+    result["model_names"] = snapshot_model_names
+    # Derive legacy model_name from the first model for backward compatibility
+    result["model_name"] = snapshot_model_names[0] if snapshot_model_names else None
 
     # Get business logic model name
     if result.get('business_logic_model_id') is not None and result['business_logic_model_id'] != 0:
@@ -363,8 +367,8 @@ def _check_version_snapshot_availability(
         return False, [AgentUnavailableReason.AGENT_NOT_FOUND]
 
     # Check model availability
-    model_id = agent_info.get('model_id')
-    if model_id is None or model_id == 0:
+    model_ids = agent_info.get('model_ids') or []
+    if not model_ids:
         unavailable_reasons.append(AgentUnavailableReason.MODEL_NOT_CONFIGURED)
 
     # Check tools availability (only when tools are configured)
@@ -628,13 +632,21 @@ def compare_versions_impl(
             'value_b': version_b.get('name'),
         })
 
-    # Compare model_name
-    if version_a.get('model_name') != version_b.get('model_name'):
+    # Compare model_ids (canonical field). Both versions should always have the
+    # same shape (list of ints) after get_version_detail_impl / draft path normalization.
+    def _normalize_model_ids(value: Any) -> List[int]:
+        if not value:
+            return []
+        return [int(x) for x in value if x is not None]
+
+    model_ids_a = _normalize_model_ids(version_a.get('model_ids'))
+    model_ids_b = _normalize_model_ids(version_b.get('model_ids'))
+    if model_ids_a != model_ids_b:
         differences.append({
-            'field': 'model_name',
+            'field': 'model_ids',
             'label': 'Model',
-            'value_a': version_a.get('model_name'),
-            'value_b': version_b.get('model_name'),
+            'value_a': version_a.get('model_names') or model_ids_a,
+            'value_b': version_b.get('model_names') or model_ids_b,
         })
 
     # Compare max_steps
@@ -752,12 +764,15 @@ def _get_version_detail_or_draft(
         # Get published version detail (already includes skills from get_version_detail_impl)
         result = get_version_detail_impl(agent_id, tenant_id, version_no)
 
-    # Get model name from model_id
-    if result.get('model_id') is not None and result['model_id'] != 0:
-        model_info = get_model_by_model_id(result['model_id'])
-        result['model_name'] = model_info.get('display_name', None) if model_info else None
-    else:
-        result['model_name'] = None
+    # Get model names from model_ids array
+    detail_model_ids = result.get("model_ids") or []
+    detail_model_names: List[str] = []
+    for mid in detail_model_ids:
+        mid_info = get_model_by_model_id(mid)
+        if mid_info and mid_info.get("display_name"):
+            detail_model_names.append(mid_info["display_name"])
+    result["model_names"] = detail_model_names
+    result["model_name"] = detail_model_names[0] if detail_model_names else None
 
     # Get business logic model name
     if result.get('business_logic_model_id') is not None and result['business_logic_model_id'] != 0:
@@ -908,12 +923,20 @@ async def list_published_agents_impl(
             agent = entry["raw_agent"]
             unavailable_reasons = list(dict.fromkeys(entry["unavailable_reasons"]))
 
-            model_id = agent.get("model_id")
-            model_info = None
-            if model_id is not None:
-                if model_id not in model_cache:
-                    model_cache[model_id] = get_model_by_model_id(model_id, tenant_id)
-                model_info = model_cache.get(model_id)
+            # Build model_ids and model_names from agent snapshot
+            model_ids_list = agent.get("model_ids")
+            model_names_list: list[str] = []
+
+            if model_ids_list:
+                # Resolve model names for each model_id
+                for mid in model_ids_list:
+                    if mid not in model_cache:
+                        model_cache[mid] = get_model_by_model_id(mid, tenant_id)
+                    model_info_item = model_cache.get(mid)
+                    if model_info_item:
+                        model_names_list.append(model_info_item.get("display_name") or model_info_item.get("model_name") or str(mid))
+                    else:
+                        model_names_list.append(str(mid))
 
             permission = resolve_agent_list_permission(
                 user_role=user_role,
@@ -928,9 +951,9 @@ async def list_published_agents_impl(
                 "display_name": agent.get("display_name") if agent.get("display_name") else agent.get("name"),
                 "description": agent.get("description"),
                 "author": agent.get("author"),
-                "model_id": model_id,
-                "model_name": model_info.get("model_name") if model_info is not None else agent.get("model_name"),
-                "model_display_name": model_info.get("display_name") if model_info is not None else None,
+                "model_ids": model_ids_list,
+                "model_names": model_names_list,
+                "model_name": model_names_list[0] if model_names_list else None,
                 "is_available": len(unavailable_reasons) == 0,
                 "unavailable_reasons": unavailable_reasons,
                 "is_new": agent.get("is_new", False),

backend/services/agent_version_service.py

@@ -326,6 +326,7 @@ async def start_streaming_chat(
     attachments: Optional[List[Any]] = None,
     meta_data: Optional[Dict[str, Any]] = None,
     tool_params: Optional[ToolParamsRequest] = None,
+    model_id: Optional[int] = None,
     idempotency_key: Optional[str] = None
 ) -> StreamingResponse:
     try:
@@ -360,6 +361,7 @@ async def start_streaming_chat(
             minio_files=normalized_attachments,
             is_debug=False,
             tool_params=tool_params,
+            model_id=model_id,
         )
 
         # Synchronously persist the user message before starting the stream to avoid race conditions

backend/services/northbound_service.py

@@ -0,0 +1,86 @@
+-- Migration: Change ag_tenant_agent_t.model_id to model_ids (list of integers)
+-- Date: 2026-06-17
+-- Description: Migrate agent model configuration from single model_id to model_ids list
+--
+-- Idempotency notes:
+-- This migration is executed on every container restart together with all other
+-- incremental migrations. The follow-up migration
+--   v2.2.2_0626_drop_agent_model_id_and_model_name.sql
+-- removes ag_tenant_agent_t.model_id (and model_name). Therefore, on a re-run
+-- the model_id column may already be absent. Every step that references
+-- model_id must be guarded so the script remains a no-op in that state.
+--
+-- Migration strategy:
+-- 1. Add new model_ids column as ARRAY(Integer) if it doesn't already exist
+--    (idempotent via ADD COLUMN IF NOT EXISTS).
+-- 2. If model_id still exists, backfill model_ids from model_id only when
+--    model_ids is NULL or an empty array. Existing non-empty values are
+--    preserved so the migration does not clobber data written by newer code.
+-- 3. Set column comments (guarded so missing columns do not error).
+
+SET search_path TO nexent;
+
+BEGIN;
+
+-- 1) Add model_ids column if it doesn't exist.
+-- ADD COLUMN IF NOT EXISTS is a no-op when the column already exists, so
+-- this statement is safe to re-run on every startup.
+ALTER TABLE nexent.ag_tenant_agent_t
+    ADD COLUMN IF NOT EXISTS model_ids INTEGER[] DEFAULT NULL;
+
+-- 2) Backfill model_ids from the legacy single-value model_id column.
+-- Only runs when model_id still exists. When model_id has already been
+-- dropped by a later migration (e.g. v2.2.2_0626_drop_agent_model_id_and_model_name.sql),
+-- this step is skipped and the script remains a safe no-op.
+-- "Empty" is defined as either NULL or an empty array ('{}'); both
+-- COALESCE(array_length(model_ids, 1), 0) = 0 and model_ids IS NULL match
+-- these cases. Rows whose model_ids already has values are left untouched.
+DO $$
+BEGIN
+    IF EXISTS (
+        SELECT 1 FROM information_schema.columns
+        WHERE table_schema = 'nexent'
+          AND table_name = 'ag_tenant_agent_t'
+          AND column_name = 'model_id'
+    ) THEN
+        UPDATE nexent.ag_tenant_agent_t
+        SET model_ids = ARRAY[model_id]
+        WHERE model_id IS NOT NULL
+          AND (model_ids IS NULL OR COALESCE(array_length(model_ids, 1), 0) = 0);
+    END IF;
+END $$;
+
+-- 3) Update column comments.
+-- model_ids is created above (or was created on an earlier run) so the
+-- comment can be applied unconditionally. COMMENT ON COLUMN raises an
+-- error if the column is missing, so we still guard it for safety.
+DO $$
+BEGIN
+    IF EXISTS (
+        SELECT 1 FROM information_schema.columns
+        WHERE table_schema = 'nexent'
+          AND table_name = 'ag_tenant_agent_t'
+          AND column_name = 'model_ids'
+    ) THEN
+        COMMENT ON COLUMN nexent.ag_tenant_agent_t.model_ids IS
+            'List of model IDs, foreign key references to model_record_t.model_id, max 5 models';
+    END IF;
+END $$;
+
+-- 4) Add a deprecation comment to model_id, only when the column still exists.
+-- Once v2.2.2_0626_drop_agent_model_id_and_model_name.sql has dropped it,
+-- this block is skipped.
+DO $$
+BEGIN
+    IF EXISTS (
+        SELECT 1 FROM information_schema.columns
+        WHERE table_schema = 'nexent'
+          AND table_name = 'ag_tenant_agent_t'
+          AND column_name = 'model_id'
+    ) THEN
+        COMMENT ON COLUMN nexent.ag_tenant_agent_t.model_id IS
+            '[DEPRECATED] Single model ID, use model_ids instead';
+    END IF;
+END $$;
+
+COMMIT;

deploy/sql/migrations/v2.2.2_0624_migrate_agent_model_id_to_list.sql

@@ -315,7 +315,14 @@ export function VersionCardItem({
     {
       key: '2',
       label: t("agent.version.field.modelName"),
-      children: <span>{agentVersionDetail?.model_name}</span>,
+      children: (
+        <span>
+          {Array.isArray((agentVersionDetail as any)?.model_names) &&
+          (agentVersionDetail as any).model_names.length > 0
+            ? (agentVersionDetail as any).model_names.join(", ")
+            : (agentVersionDetail as any)?.model_name || "-"}
+        </span>
+      ),
     },
   ];
 

frontend/app/[locale]/agents/AgentVersionCard.tsx

@@ -262,14 +262,24 @@ export default function AgentSelectorHeader({
         .map((id: any) => Number(id))
         .filter((id: number) => Number.isFinite(id));
 
+      // Ensure model_ids always has a value - fall back to single-element array
+      // using the agent's first available legacy model_id (single-select) when
+      // model_ids is empty in the response.
+      const modelIdsForCopy = (() => {
+        if (detail.model_ids && detail.model_ids.length > 0) return detail.model_ids;
+        // Legacy payload may only carry model_id (single-select); preserve it
+        const legacySingleId = (detail as { model_id?: number }).model_id;
+        if (legacySingleId) return [legacySingleId];
+        return undefined;
+      })();
+
       const createResult = await updateAgentMutation.mutateAsync({
         agent_id: undefined, // create
         name: copyName,
         display_name: copyDisplayName,
         description: detail.description,
         author: detail.author,
-        model_name: detail.model,
-        model_id: detail.model_id ?? undefined,
+        model_ids: modelIdsForCopy,
         max_steps: detail.max_step,
         requested_output_tokens: detail.requested_output_tokens ?? null,
         provide_run_summary: detail.provide_run_summary,