feat(api): Agent App type S1 — AppMode.AGENT + create flow + binding (#36829)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

api/controllers/console/__init__.py

@@ -51,6 +51,8 @@ from .agent import roster as agent_roster
 from .app import (
     advanced_prompt_template,
     agent,
+    agent_app_access,
+    agent_app_feature,
     annotation,
     app,
     audio,
@@ -146,6 +148,8 @@ __all__ = [
     "activate",
     "advanced_prompt_template",
     "agent",
+    "agent_app_access",
+    "agent_app_feature",
     "agent_composer",
     "agent_providers",
     "agent_roster",

api/controllers/console/app/agent_app_access.py

@@ -0,0 +1,59 @@
+"""Agent App access & sharing endpoints (read-only workflow references).
+
+An Agent App is backed by a roster Agent that workflow Agent nodes may also
+reference. This exposes the read-only "Workflow access" surface from the PRD:
+which workflow apps use this Agent, without leaking the workflows' internals.
+"""
+
+from flask_restx import Resource
+from pydantic import Field
+
+from controllers.common.schema import register_response_schema_models
+from controllers.console import console_ns
+from controllers.console.app.wraps import get_app_model
+from controllers.console.wraps import account_initialization_required, setup_required
+from extensions.ext_database import db
+from fields.base import ResponseModel
+from libs.login import current_account_with_tenant, login_required
+from models.model import App, AppMode
+from services.agent.roster_service import AgentRosterService
+
+
+class AgentReferencingWorkflowResponse(ResponseModel):
+    app_id: str
+    app_name: str
+    app_mode: str
+    workflow_id: str
+    node_ids: list[str] = Field(default_factory=list)
+
+
+class AgentReferencingWorkflowsResponse(ResponseModel):
+    data: list[AgentReferencingWorkflowResponse] = Field(default_factory=list)
+
+
+register_response_schema_models(console_ns, AgentReferencingWorkflowsResponse)
+
+
+@console_ns.route("/apps/<uuid:app_id>/agent-referencing-workflows")
+class AgentAppReferencingWorkflowsResource(Resource):
+    @console_ns.doc("list_agent_app_referencing_workflows")
+    @console_ns.doc(description="List workflow apps that reference this Agent App's bound Agent (read-only)")
+    @console_ns.doc(params={"app_id": "Application ID"})
+    @console_ns.response(
+        200,
+        "Referencing workflows listed successfully",
+        console_ns.models[AgentReferencingWorkflowsResponse.__name__],
+    )
+    @console_ns.response(404, "App not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=[AppMode.AGENT])
+    def get(self, app_model: App):
+        _, tenant_id = current_account_with_tenant()
+        workflows = AgentRosterService(db.session).list_workflows_referencing_app_agent(
+            tenant_id=tenant_id, app_id=app_model.id
+        )
+        return AgentReferencingWorkflowsResponse(
+            data=[AgentReferencingWorkflowResponse.model_validate(workflow) for workflow in workflows]
+        ).model_dump(mode="json")

api/controllers/console/app/agent_app_feature.py

@@ -0,0 +1,80 @@
+"""Agent App presentation-feature configuration endpoint.
+
+The new Agent App type keeps model / prompt / tools in its bound Agent Soul, so
+the legacy ``/model-config`` surface (which writes model, prompt and agent tool
+config) is the wrong place to configure its app-level presentation features.
+This endpoint exposes only the PRD "Misc Legacy" feature subset — conversation
+opener, follow-up suggestions, citations, content moderation and speech — and
+persists them onto the app's ``app_model_config`` without touching anything the
+Soul owns.
+"""
+
+from typing import Any
+
+from flask_restx import Resource
+from pydantic import BaseModel, Field
+
+from controllers.common.fields import SimpleResultResponse
+from controllers.common.schema import register_response_schema_models, register_schema_models
+from controllers.console import console_ns
+from controllers.console.app.wraps import get_app_model
+from controllers.console.wraps import account_initialization_required, edit_permission_required, setup_required
+from events.app_event import app_model_config_was_updated
+from libs.login import current_account_with_tenant, login_required
+from models.model import App, AppMode
+from services.agent_app_feature_service import AgentAppFeatureConfigService
+
+
+class AgentAppFeaturesRequest(BaseModel):
+    """Presentation features configurable on an Agent App.
+
+    All fields are optional; an omitted field is reset to its disabled/empty
+    default (the config form sends the full desired feature state on save).
+    """
+
+    opening_statement: str | None = Field(default=None, description="Conversation opener shown before the first turn")
+    suggested_questions: list[str] | None = Field(
+        default=None, description="Preset questions shown alongside the opener"
+    )
+    suggested_questions_after_answer: dict[str, Any] | None = Field(
+        default=None, description="Follow-up suggestions config, e.g. {'enabled': true}"
+    )
+    speech_to_text: dict[str, Any] | None = Field(default=None, description="Speech-to-text config")
+    text_to_speech: dict[str, Any] | None = Field(default=None, description="Text-to-speech config")
+    retriever_resource: dict[str, Any] | None = Field(
+        default=None, description="Citations / attributions config, e.g. {'enabled': true}"
+    )
+    sensitive_word_avoidance: dict[str, Any] | None = Field(default=None, description="Content moderation config")
+
+
+register_schema_models(console_ns, AgentAppFeaturesRequest)
+register_response_schema_models(console_ns, SimpleResultResponse)
+
+
+@console_ns.route("/apps/<uuid:app_id>/agent-features")
+class AgentAppFeatureConfigResource(Resource):
+    @console_ns.doc("update_agent_app_features")
+    @console_ns.doc(description="Update an Agent App's presentation features (opener, follow-up, citations, ...)")
+    @console_ns.doc(params={"app_id": "Application ID"})
+    @console_ns.expect(console_ns.models[AgentAppFeaturesRequest.__name__])
+    @console_ns.response(200, "Features updated successfully", console_ns.models[SimpleResultResponse.__name__])
+    @console_ns.response(400, "Invalid configuration")
+    @console_ns.response(404, "App not found")
+    @setup_required
+    @login_required
+    @edit_permission_required
+    @account_initialization_required
+    @get_app_model(mode=[AppMode.AGENT])
+    def post(self, app_model: App):
+        args = AgentAppFeaturesRequest.model_validate(console_ns.payload)
+        current_user, _ = current_account_with_tenant()
+
+        new_app_model_config = AgentAppFeatureConfigService.update_features(
+            app_model=app_model,
+            account=current_user,
+            config=args.model_dump(exclude_none=True),
+        )
+
+        app_model_config_was_updated.send(app_model, app_model_config=new_app_model_config)
+
+        return {"result": "success"}

api/controllers/console/app/app.py

@@ -55,7 +55,7 @@ from services.entities.knowledge_entities.knowledge_entities import (
 )
 from services.feature_service import FeatureService
 
-ALLOW_CREATE_APP_MODES = ["chat", "agent-chat", "advanced-chat", "workflow", "completion"]
+ALLOW_CREATE_APP_MODES = ["chat", "agent-chat", "agent", "advanced-chat", "workflow", "completion"]
 
 register_enum_models(console_ns, IconType)
 
@@ -66,7 +66,7 @@ _TAG_IDS_BRACKET_PATTERN = re.compile(r"^tag_ids\[(\d+)\]$")
 class AppListQuery(BaseModel):
     page: int = Field(default=1, ge=1, le=99999, description="Page number (1-99999)")
     limit: int = Field(default=20, ge=1, le=100, description="Page size (1-100)")
-    mode: Literal["completion", "chat", "advanced-chat", "workflow", "agent-chat", "channel", "all"] = Field(
+    mode: Literal["completion", "chat", "advanced-chat", "workflow", "agent-chat", "agent", "channel", "all"] = Field(
         default="all", description="App mode filter"
     )
     name: str | None = Field(default=None, description="Filter by app name")
@@ -115,7 +115,9 @@ def _normalize_app_list_query_args(query_args: MultiDict[str, str]) -> dict[str,
 class CreateAppPayload(BaseModel):
     name: str = Field(..., min_length=1, description="App name")
     description: str | None = Field(default=None, description="App description (max 400 chars)", max_length=400)
-    mode: Literal["chat", "agent-chat", "advanced-chat", "workflow", "completion"] = Field(..., description="App mode")
+    mode: Literal["chat", "agent-chat", "agent", "advanced-chat", "workflow", "completion"] = Field(
+        ..., description="App mode"
+    )
     icon_type: IconType | None = Field(default=None, description="Icon type")
     icon: str | None = Field(default=None, description="Icon")
     icon_background: str | None = Field(default=None, description="Icon background color")
@@ -393,6 +395,8 @@ class AppDetailWithSite(AppDetail):
     max_active_requests: int | None = None
     deleted_tools: list[DeletedTool] = Field(default_factory=list)
     site: Site | None = None
+    # For Agent App type: the roster Agent backing this app (None otherwise).
+    bound_agent_id: str | None = None
 
     @computed_field(return_type=str | None)  # type: ignore
     @property

api/controllers/console/app/completion.py

@@ -4,7 +4,7 @@ from typing import Any, Literal
 from flask import request
 from flask_restx import Resource
 from pydantic import BaseModel, Field, field_validator
-from werkzeug.exceptions import InternalServerError, NotFound
+from werkzeug.exceptions import BadRequest, InternalServerError, NotFound
 
 import services
 from controllers.common.fields import SimpleResultResponse
@@ -41,9 +41,24 @@ from services.errors.llm import InvokeRateLimitError
 logger = logging.getLogger(__name__)
 
 
+def _resolve_debugger_chat_streaming(
+    *, app_mode: AppMode, response_mode: str, response_mode_provided: bool = True
+) -> bool:
+    """Agent App runtime is SSE-only until backend blocking runs are supported."""
+    if app_mode != AppMode.AGENT:
+        return response_mode != "blocking"
+    if response_mode_provided and response_mode == "blocking":
+        raise BadRequest("Agent App only supports streaming response mode.")
+    return True
+
+
 class BaseMessagePayload(BaseModel):
     inputs: dict[str, Any]
-    model_config_data: dict[str, Any] = Field(..., alias="model_config")
+    # Agent Apps (AppMode.AGENT) derive their model + prompt from the bound Agent
+    # Soul, so no override ``model_config`` is sent; chat / agent-chat / completion
+    # debugging still pass it. Optional here, required in practice by those modes
+    # downstream when their config is built from args.
+    model_config_data: dict[str, Any] = Field(default_factory=dict, alias="model_config")
     files: list[Any] | None = Field(default=None, description="Uploaded files")
     response_mode: Literal["blocking", "streaming"] = Field(default="blocking", description="Response mode")
     retriever_from: str = Field(default="dev", description="Retriever source")
@@ -157,13 +172,20 @@ class ChatMessageApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT])
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.AGENT])
     @edit_permission_required
     def post(self, app_model: App):
-        args_model = ChatMessagePayload.model_validate(console_ns.payload)
+        raw_payload = console_ns.payload or {}
+        args_model = ChatMessagePayload.model_validate(raw_payload)
         args = args_model.model_dump(exclude_none=True, by_alias=True)
 
-        streaming = args_model.response_mode != "blocking"
+        streaming = _resolve_debugger_chat_streaming(
+            app_mode=AppMode.value_of(app_model.mode),
+            response_mode=args_model.response_mode,
+            response_mode_provided=isinstance(raw_payload, dict) and "response_mode" in raw_payload,
+        )
+        if AppMode.value_of(app_model.mode) == AppMode.AGENT:
+            args["response_mode"] = "streaming"
         args["auto_generate_name"] = False
 
         external_trace_id = get_external_trace_id(request)
@@ -211,7 +233,7 @@ class ChatMessageStopApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT])
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     def post(self, app_model: App, task_id: str):
         if not isinstance(current_user, Account):
             raise ValueError("current_user must be an Account instance")

api/controllers/console/app/conversation.py

@@ -212,7 +212,7 @@ class ChatConversationApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT])
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @edit_permission_required
     @with_current_user
     def get(self, current_user: Account, app_model: App):
@@ -323,7 +323,7 @@ class ChatConversationDetailApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT])
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @edit_permission_required
     @with_current_user
     def get(self, current_user: Account, app_model: App, conversation_id: UUID):
@@ -340,7 +340,7 @@ class ChatConversationDetailApi(Resource):
     @console_ns.response(404, "Conversation not found")
     @setup_required
     @login_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT])
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @account_initialization_required
     @edit_permission_required
     @with_current_user

api/controllers/console/app/message.py

@@ -180,7 +180,7 @@ class ChatMessageListApi(Resource):
     @login_required
     @account_initialization_required
     @setup_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT])
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @edit_permission_required
     def get(self, app_model: App):
         args = ChatMessagesQuery.model_validate(request.args.to_dict())
@@ -337,7 +337,7 @@ class MessageSuggestedQuestionApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT])
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @with_current_user
     def get(self, current_user: Account, app_model: App, message_id: UUID):
         message_id_str = str(message_id)

api/controllers/console/app/statistic.py

@@ -290,7 +290,7 @@ class AverageSessionInteractionStatistic(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT])
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @with_current_user
     def get(self, account: Account, app_model: App):
         args = StatisticTimeRangeQuery.model_validate(request.args.to_dict(flat=True))