Feat: bundled default agents

backend/agents/create_agent_info.py

@@ -79,6 +79,8 @@
     LANGUAGE,
     LLM_INCLUDE_LOGPROBS,
     LOCAL_MCP_SERVER,
+    get_tenant_local_mcp_server,
+    TOKEN,
     MINIO_DEFAULT_BUCKET,
     MODEL_CONFIG_MAPPING,
     NEXENT_SANDBOX_WORKSPACE_VOLUME,
@@ -2375,7 +2377,7 @@ async def create_agent_run_info(
                     break
 
     remote_mcp_list = await get_remote_mcp_server_list(tenant_id=tenant_id, is_need_auth=True)
-    default_mcp_url = urljoin(LOCAL_MCP_SERVER, "sse")
+    default_mcp_url = get_tenant_local_mcp_server(tenant_id)
     remote_mcp_list.append({
         "remote_mcp_server_name": "outer-apis",
         "remote_mcp_server": default_mcp_url,
@@ -2404,6 +2406,10 @@ async def create_agent_run_info(
             }
             if url == default_mcp_url:
                 mcp_config["httpx_client_factory"] = create_httpx_client
+                mcp_config["headers"] = {
+                    "X-Tenant-ID": str(tenant_id),
+                    "X-Nexent-Internal-Token": TOKEN,
+                }
             headers = {}
             auth_token = mcp_record.get("authorization_token")
             if auth_token:

backend/apps/agent_repository_app.py

@@ -310,17 +310,33 @@ async def check_repository_import_precheck_api(
 @agent_repository_router.post("/{agent_repository_id}/import")
 async def import_agent_from_repository_api(
     agent_repository_id: int,
-    skill_resolutions: Optional[list[SkillResolution]] = Body(default=None),
+    payload: Optional[object] = Body(default=None),
     authorization: Optional[str] = Header(None),
 ):
     """Import an agent tree from a marketplace repository listing into the current tenant."""
     try:
-        _, tenant_id = get_current_user_id(authorization)
+        user_id, tenant_id = get_current_user_id(authorization)
+        skill_resolutions = None
+        model_ids = None
+        embedding_model_ids = None
+        if isinstance(payload, list):
+            skill_resolutions = [SkillResolution.model_validate(item) for item in payload]
+        elif isinstance(payload, dict):
+            skill_resolutions = [
+                SkillResolution.model_validate(item)
+                for item in (payload.get("skill_resolutions") or [])
+            ] or None
+            model_ids = payload.get("model_ids")
+            embedding_model_ids = payload.get("embedding_model_ids")
+
         await import_agent_from_repository_impl(
             agent_repository_id=agent_repository_id,
             tenant_id=tenant_id,
             authorization=authorization,
             skill_resolutions=skill_resolutions,
+            model_ids=model_ids,
+            embedding_model_ids=embedding_model_ids,
+            user_id=user_id,
         )
         return JSONResponse(status_code=HTTPStatus.OK, content={})
     except UnauthorizedError as e:

backend/apps/tag_management_app.py

@@ -52,6 +52,11 @@ def _require_manage_context(authorization: str | None) -> tuple[str, str, str]:
     return user_id, tenant_id, role
 
 
+def _require_read_context(authorization: str | None) -> tuple[str, str, str]:
+    """Return the authenticated tenant context for read-only tag metadata."""
+    return get_current_user_context(authorization)
+
+
 def _assignment_caller(authorization: str | None) -> AuthenticatedCaller:
     user_id, tenant_id, role = get_current_user_context(authorization)
     return AuthenticatedCaller(
@@ -285,7 +290,7 @@ async def replace_resource_tag_assignments(
 
 @router.get("", response_model=list[TagLibraryResponse])
 def list_tag_libraries(authorization: str | None = Header(None)):
-    _, tenant_id, _ = _require_manage_context(authorization)
+    _, tenant_id, _ = _require_read_context(authorization)
     try:
         return TagManagementService.list_libraries(tenant_id)
     except TagManagementNotFoundError as error:
@@ -301,7 +306,7 @@ def list_tag_libraries(authorization: str | None = Header(None)):
 
 @router.get("/{bucket_id}/definitions", response_model=list[TagDefinitionResponse])
 def list_tag_definitions(bucket_id: int, authorization: str | None = Header(None)):
-    _, tenant_id, _ = _require_manage_context(authorization)
+    _, tenant_id, _ = _require_read_context(authorization)
     try:
         return TagManagementService.list_definitions(tenant_id, bucket_id)
     except TagManagementNotFoundError as error:

backend/apps/tool_config_app.py

@@ -244,6 +244,10 @@ async def import_openapi_service_api(
         mcp_result = _refresh_openapi_services_in_mcp(tenant_id)
         result["mcp_refresh"] = mcp_result
 
+        # The agent configuration page reads the persisted tool list. Refreshing
+        # the MCP runtime alone does not make newly imported tools selectable.
+        await update_tool_list(tenant_id=tenant_id, user_id=user_id)
+
         return JSONResponse(
             status_code=HTTPStatus.OK,
             content={

backend/consts/const.py

@@ -1,6 +1,7 @@
 import os
 from enum import Enum
 from pathlib import Path
+from urllib.parse import quote, urljoin
 from dotenv import load_dotenv
 
 # Load environment variables
@@ -103,7 +104,18 @@ class VectorDatabaseType(str, Enum):
 CONTAINER_SKILLS_PATH = os.getenv("SKILLS_PATH")
 
 # Container-internal official skills ZIP directory
-OFFICIAL_SKILLS_ZIP_PATH = "/mnt/nexent/official-skills-zip"
+OFFICIAL_SKILLS_ZIP_PATH = os.getenv(
+    "OFFICIAL_SKILLS_ZIP_PATH", "/mnt/nexent/official-skills-zip"
+)
+
+# Container-internal official agents bundle directory (one JSON per agent)
+OFFICIAL_AGENTS_PATH = os.getenv(
+    "OFFICIAL_AGENTS_PATH", "/mnt/nexent/official-agents"
+)
+
+OFFICIAL_AGENT_PROFILES = os.getenv("OFFICIAL_AGENT_PROFILES", "")
+OFFICIAL_AGENT_TENANT_ID = "__nexent_official__"
+OFFICIAL_AGENT_USER_ID = "__nexent_system__"
 
 
 # Preview Configuration
@@ -517,6 +529,13 @@ class VectorDatabaseType(str, Enum):
 MCP_MANAGEMENT_API = os.getenv("MCP_MANAGEMENT_API", "http://localhost:5015")
 
 
+def get_tenant_local_mcp_server(tenant_id: str) -> str:
+    """Return the tenant-scoped SSE endpoint for built-in/API-converted tools."""
+    if not tenant_id:
+        raise ValueError("tenant_id is required for the local MCP endpoint")
+    return urljoin(LOCAL_MCP_SERVER.rstrip("/") + "/", f"mcp/{quote(str(tenant_id), safe='')}/sse")
+
+
 # Invite code
 INVITE_CODE = os.getenv("INVITE_CODE")
 

backend/consts/model.py

@@ -1318,6 +1318,157 @@ class AgentRepositorySnapshot(ExportAndImportDataFormat):
     skills: Optional[List["SkillZipEntry"]] = None
 
 
+# ---------------------------------------------------------------------------
+# Official agent bundles (platform-provided, mirroring official skills)
+# ---------------------------------------------------------------------------
+
+
+class KnowledgeBaseSeedDoc(BaseModel):
+    """A seed document in an official agent bundle's knowledge base.
+
+    Text seeds carry ``content``; binary seeds (docx/pdf/...) carry ``file_path``
+    pointing at the real file on disk (set by the loader for directory layouts,
+    so the install pipeline can upload it like a normal KB document). At least
+    one of the two is set.
+    """
+    file_name: str
+    content: Optional[str] = None
+    file_path: Optional[str] = None
+
+
+class KnowledgeBaseSeed(BaseModel):
+    """Knowledge base declaration inside an official agent bundle.
+
+    ``logical_index_name`` is the bundle-local reference that agent tools point
+    to; it is remapped to the tenant's real generated index name on install.
+    """
+    logical_index_name: str
+    display_name: Optional[str] = None
+    description: Optional[str] = None
+    documents: List[KnowledgeBaseSeedDoc] = []
+
+
+class OfficialAgentBundle(AgentRepositorySnapshot):
+    """Official agent bundle: marketplace snapshot plus official card fields.
+
+    Reuses AgentRepositorySnapshot (agent_info / mcp_info / skills) and adds
+    official card metadata plus optional knowledge base seed documents.
+    An empty ``knowledge_bases`` list means the agent has no KB dependency.
+
+    Card fields are optional: when omitted they are derived from the root agent
+    (name / display_name) or sensible defaults (icon, version_label), so a bare
+    export can be used directly as a bundle without manual card editing.
+    """
+    name: Optional[str] = None
+    display_name: Optional[str] = None
+    description: Optional[str] = None
+    icon: Optional[str] = None
+    tags: List[str] = []
+    version_label: Optional[str] = None
+    knowledge_bases: List[KnowledgeBaseSeed] = []
+
+    @model_validator(mode="after")
+    def _derive_card_fields(self) -> "OfficialAgentBundle":
+        root_agent = self.agent_info.get(str(self.agent_id))
+        root_name = getattr(root_agent, "name", None) if root_agent else None
+        root_display_name = (
+            getattr(root_agent, "display_name", None) if root_agent else None
+        )
+        if not self.name:
+            self.name = root_name or "agent"
+        if not self.display_name:
+            self.display_name = root_display_name or self.name
+        if not self.icon:
+            self.icon = "🤖"
+        if not self.version_label:
+            self.version_label = "V1"
+        return self
+
+
+OfficialAgentStatus = Literal[
+    "installed", "needs_model", "installable"
+]
+
+
+class OfficialAgentAgentInfo(BaseModel):
+    """An agent inside an official bundle (root or sub-agent) for conflict pre-check."""
+    name: str
+    display_name: Optional[str] = None
+
+
+class OfficialAgentMcpPreview(BaseModel):
+    """MCP server declaration inside an official bundle, with per-tenant install state."""
+    mcp_server_name: str
+    mcp_url: str
+    installed: bool = False
+
+
+class OfficialAgentListItem(BaseModel):
+    """Single item in the GET /repository/agent/official response."""
+    name: str
+    display_name: Optional[str] = None
+    description: Optional[str] = None
+    icon: Optional[str] = None
+    tags: List[str] = []
+    version_label: Optional[str] = None
+    status: OfficialAgentStatus
+    has_knowledge: bool
+    mcp_count: int
+    skill_count: int
+    kb_count: int
+    missing_models: List[str] = []
+    agents: List[OfficialAgentAgentInfo] = []
+    mcps: List[OfficialAgentMcpPreview] = []
+
+
+OfficialAgentInstallStatus = Literal[
+    "installed", "needs_model", "already_installed", "not_found", "failed"
+]
+
+OfficialAgentInstallStepStatus = Literal["ok", "failed"]
+
+
+class OfficialAgentInstallStep(BaseModel):
+    """One step of an official agent install (mcp / tools / knowledge_base / agent).
+
+    ``status`` is "ok" when the step completed, "failed" when it raised (the
+    install aborts and the failed step's message explains why).
+    """
+    name: str
+    status: OfficialAgentInstallStepStatus
+    message: Optional[str] = None
+
+
+class OfficialAgentInstallRequest(BaseModel):
+    """Request body for installing official agents.
+
+    ``renames`` maps an existing agent name inside a bundle to a new name
+    (used to resolve name conflicts before import). ``model_ids`` maps a bundle
+    key to a tenant LLM model_id applied to the bundle's root agent on install.
+    """
+    agent_names: List[str] = Field(
+        ..., min_length=1, description="Official agent bundle names to install"
+    )
+    renames: Optional[Dict[str, str]] = None
+    model_ids: Optional[Dict[str, int]] = None
+    embedding_model_ids: Optional[Dict[str, int]] = None
+
+
+class OfficialAgentInstallItem(BaseModel):
+    """Per-agent result of an official agent install request."""
+    name: str
+    status: OfficialAgentInstallStatus
+    message: Optional[str] = None
+    steps: Optional[List[OfficialAgentInstallStep]] = None
+    missing_models: List[str] = []
+    agent_id: Optional[int] = None
+
+
+class OfficialAgentInstallResponse(BaseModel):
+    """Response payload for POST /repository/agent/official/install."""
+    results: List[OfficialAgentInstallItem]
+
+
 RepositoryImportRequirementType = Literal[
     "model", "knowledge_base", "mcp", "skill", "tool"
 ]

backend/database/agent_db.py

@@ -279,7 +279,7 @@
             AgentInfo.delete_flag != 'Y'
         ).first()
         if not agent:
             raise ValueError("ag_tenant_agent_t Agent not found")
 
         agent_data = dict(agent_info.__dict__)
         fields_set = getattr(agent_info, "model_fields_set", None)
@@ -311,6 +311,24 @@
             raise ValueError("ag_tenant_agent_t Agent not found")
 
 
+def update_agent_display_name(
+    agent_id: int, tenant_id: str, display_name: str, user_id: str
+) -> None:
+    """Update the display name on every active version of an agent."""
+    with get_db_session() as session:
+        result = session.execute(
+            update(AgentInfo)
+            .where(
+                AgentInfo.agent_id == agent_id,
+                AgentInfo.tenant_id == tenant_id,
+                AgentInfo.delete_flag == "N",
+            )
+            .values(display_name=display_name, updated_by=user_id)
+        )
+        if result.rowcount == 0:
+            raise ValueError("ag_tenant_agent_t Agent not found")
+
+
 def query_agent_records_for_nl2agent(agent_id: int, tenant_id: str) -> list[dict]:
     """Return all tenant-owned records for NL2Agent draft validation.
 

backend/database/agent_repository_db.py

@@ -227,6 +227,7 @@ def update_agent_repository_by_id(
     """Update a repository listing owned by the publisher tenant. Returns affected row count."""
     allowed_fields = {
         "display_name",
+        "name",
         "description",
         "author",
         "submitted_by",
@@ -486,4 +487,3 @@ def fetch_draft_agent_mine_metadata(
         }
         for row in rows
     }
-