agentscope-runtime 0.2.0b1__py3-none-any.whl → 1.0.0__py3-none-any.whl

agentscope_runtime/common/container_clients/kubernetes_client.py

@@ -1,11 +1,10 @@
 # -*- coding: utf-8 -*-
-# pylint: disable=too-many-branches, self-assigning-variable
-# pylint: disable=too-many-statements
-
-import hashlib
-import logging
+# pylint: disable=too-many-branches,too-many-statements
 import time
+import hashlib
 import traceback
+import logging
+
 from typing import Optional, Tuple
 
 from kubernetes import client
@@ -16,14 +15,12 @@ from .base_client import BaseClient
 
 logger = logging.getLogger(__name__)
 
-DEFAULT_IMAGE_REGISTRY = "agentscope-registry.ap-southeast-1.cr.aliyuncs.com"
-
 
 class KubernetesClient(BaseClient):
     def __init__(
         self,
         config=None,
-        image_registry: Optional[str] = DEFAULT_IMAGE_REGISTRY,
+        image_registry: Optional[str] = None,
     ):
         self.config = config
         namespace = self.config.k8s_namespace
@@ -157,11 +154,7 @@ class KubernetesClient(BaseClient):
         container_name = name or "main-container"
 
         # Container specification
-        # TODO: use image from docker registry first
-
-        if not self.image_registry:
-            image = image
-        else:
+        if self.image_registry:
             image = f"{self.image_registry}/{image}"
 
         container = client.V1Container(

agentscope_runtime/common/utils/lazy_loader.py

@@ -0,0 +1,57 @@
+# -*- coding: utf-8 -*-
+import importlib
+
+
+def install_lazy_loader(globals_dict, lazy_map):
+    """
+    Install __getattr__ and __all__ for lazy loading of module members.
+
+    Args:
+        globals_dict: The globals() of the current module.
+                      Pass the globals() from the module where this is called.
+        lazy_map: dict[name, module_path]
+                  OR dict[name, dict(module=..., hint=...)]
+                  The hint is an optional message for missing dependencies.
+    """
+    __all__ = list(lazy_map.keys())
+
+    def __getattr__(name):
+        if name in lazy_map:
+            entry = lazy_map[name]
+            module_path, hint = None, None
+
+            # Support two configuration formats
+            if isinstance(entry, str):
+                module_path = entry
+            elif isinstance(entry, dict):
+                module_path = entry["module"]
+                hint = entry.get("hint")
+
+            try:
+                module = importlib.import_module(
+                    module_path,
+                    globals_dict["__name__"],
+                )
+            except ImportError as e:
+                msg = f"Failed to import {name}. Possible missing dependency."
+                if hint:
+                    msg += f" Please install dependency: {hint}"
+                else:
+                    msg += (
+                        " Please install dependency:  pip install "
+                        "agentscope-runtime[ext]"
+                    )
+                raise ImportError(msg) from e
+
+            obj = getattr(module, name)
+            # Cache in globals to avoid reloading
+            globals_dict[name] = obj
+            return obj
+
+        raise AttributeError(
+            f"module {globals_dict['__name__']} has no attribute {name}",
+        )
+
+    # Modify the globals of the calling module
+    globals_dict["__all__"] = __all__
+    globals_dict["__getattr__"] = __getattr__

agentscope_runtime/engine/__init__.py

@@ -1,21 +1,28 @@
 # -*- coding: utf-8 -*-
-from .services import (
-    Service,
-    SandboxService,
-    MemoryService,
-    SessionHistoryService,
-)
-from .deployers import DeployManager, LocalDeployManager
-from .runner import Runner
+
+from typing import TYPE_CHECKING
+
 from .app import AgentApp
+from .runner import Runner
+from ..common.utils.lazy_loader import install_lazy_loader
+
+if TYPE_CHECKING:
+    from .deployers import (
+        DeployManager,
+        LocalDeployManager,
+        KubernetesDeployManager,
+        ModelstudioDeployManager,
+        AgentRunDeployManager,
+    )
 
-__all__ = [
-    "Service",
-    "SandboxService",
-    "MemoryService",
-    "SessionHistoryService",
-    "DeployManager",
-    "LocalDeployManager",
-    "Runner",
-    "AgentApp",
-]
+
+install_lazy_loader(
+    globals(),
+    {
+        "DeployManager": ".deployers",
+        "LocalDeployManager": ".deployers",
+        "KubernetesDeployManager": ".deployers",
+        "ModelstudioDeployManager": ".deployers",
+        "AgentRunDeployManager": ".deployers",
+    },
+)

agentscope_runtime/engine/app/agent_app.py

@@ -1,28 +1,23 @@
 # -*- coding: utf-8 -*-
-import asyncio
 import logging
-from contextlib import asynccontextmanager
-from typing import Optional, Any, Callable, List
+import types
+import subprocess
+import shlex
+from typing import Optional, Callable, List
 
 import uvicorn
-from fastapi import FastAPI
 from pydantic import BaseModel
 
 from .base_app import BaseApp
-from ..agents.base_agent import Agent
+from ..deployers import DeployManager
 from ..deployers.adapter.a2a import A2AFastAPIDefaultAdapter
 from ..deployers.adapter.responses.response_api_protocol_adapter import (
     ResponseAPIDefaultAdapter,
 )
 from ..deployers.utils.deployment_modes import DeploymentMode
 from ..deployers.utils.service_utils.fastapi_factory import FastAPIAppFactory
-from ..deployers.utils.service_utils.service_config import (
-    DEFAULT_SERVICES_CONFIG,
-)
 from ..runner import Runner
 from ..schemas.agent_schemas import AgentRequest
-from ..services.context_manager import ContextManager
-from ..services.environment_manager import EnvironmentManager
 from ...version import __version__
 
 logger = logging.getLogger(__name__)
@@ -36,9 +31,8 @@ class AgentApp(BaseApp):
     def __init__(
         self,
         *,
-        agent: Optional[Agent] = None,
-        environment_manager: Optional[EnvironmentManager] = None,
-        context_manager: Optional[ContextManager] = None,
+        app_name: str = "",
+        app_description: str = "",
         endpoint_path: str = "/process",
         response_type: str = "sse",
         stream: bool = True,
@@ -47,6 +41,8 @@ class AgentApp(BaseApp):
         after_finish: Optional[Callable] = None,
         broker_url: Optional[str] = None,
         backend_url: Optional[str] = None,
+        runner: Optional[Runner] = None,
+        enable_embedded_worker: bool = False,
         **kwargs,
     ):
         """
@@ -65,135 +61,209 @@ class AgentApp(BaseApp):
         self.after_finish = after_finish
         self.broker_url = broker_url
         self.backend_url = backend_url
+        self.enable_embedded_worker = enable_embedded_worker
 
-        self._agent = agent
-        self._runner = None
+        self._runner = runner
         self.custom_endpoints = []  # Store custom endpoints
 
-        a2a_protocol = A2AFastAPIDefaultAdapter(agent=self._agent)
+        # Custom Handlers
+        self._query_handler: Optional[Callable] = None
+        self._init_handler: Optional[Callable] = None
+        self._shutdown_handler: Optional[Callable] = None
+        self._framework_type: Optional[str] = None
+
+        a2a_protocol = A2AFastAPIDefaultAdapter(
+            agent_name=app_name,
+            agent_description=app_description,
+        )
+
         response_protocol = ResponseAPIDefaultAdapter()
         self.protocol_adapters = [a2a_protocol, response_protocol]
 
-        if self._agent:
-            self._runner = Runner(
-                agent=self._agent,
-                environment_manager=environment_manager,
-                context_manager=context_manager,
-            )
-
-        @asynccontextmanager
-        async def lifespan(app: FastAPI) -> Any:
-            """Manage the application lifespan."""
-            if hasattr(self, "before_start") and self.before_start:
-                if asyncio.iscoroutinefunction(self.before_start):
-                    await self.before_start(app, **getattr(self, "kwargs", {}))
-                else:
-                    self.before_start(app, **getattr(self, "kwargs", {}))
-            yield
-            if hasattr(self, "after_finish") and self.after_finish:
-                if asyncio.iscoroutinefunction(self.after_finish):
-                    await self.after_finish(app, **getattr(self, "kwargs", {}))
-                else:
-                    self.after_finish(app, **getattr(self, "kwargs", {}))
-
-        kwargs = {
+        self._app_kwargs = {
             "title": "Agent Service",
             "version": __version__,
             "description": "Production-ready Agent Service API",
-            "lifespan": lifespan,
             **kwargs,
         }
 
-        if self._runner:
-            if self.stream:
-                self.func = self._runner.stream_query
-            else:
-                self.func = self._runner.query
-
         super().__init__(
             broker_url=broker_url,
             backend_url=backend_url,
-            **kwargs,
         )
 
         # Store custom endpoints and tasks for deployment
         # but don't add them to FastAPI here - let FastAPIAppFactory handle it
 
+    def init(self, func):
+        """Register init hook (support async and sync functions)."""
+        self._init_handler = func
+        return func
+
+    def query(self, framework: Optional[str] = "agentscope"):
+        """
+        Register run hook and optionally specify agent framework.
+        Allowed framework values: 'agentscope', 'autogen', 'agno', 'langgraph'.
+        """
+
+        allowed_frameworks = {"agentscope", "autogen", "agno", "langgraph"}
+        if framework not in allowed_frameworks:
+            raise ValueError(f"framework must be one of {allowed_frameworks}")
+
+        def decorator(func):
+            self._query_handler = func
+            self._framework_type = framework
+            return func
+
+        return decorator
+
+    def shutdown(self, func):
+        """Register shutdown hook (support async and sync functions)."""
+        self._shutdown_handler = func
+        return func
+
+    def _build_runner(self):
+        if self._runner is None:
+            self._runner = Runner()
+
+        if self._framework_type is not None:
+            self._runner.framework_type = self._framework_type
+
+        if self._query_handler is not None:
+            self._runner.query_handler = types.MethodType(
+                self._query_handler,
+                self._runner,
+            )
+
+        if self._init_handler is not None:
+            self._runner.init_handler = types.MethodType(
+                self._init_handler,
+                self._runner,
+            )
+
+        if self._shutdown_handler is not None:
+            self._runner.shutdown_handler = types.MethodType(
+                self._shutdown_handler,
+                self._runner,
+            )
+
     def run(
         self,
         host="0.0.0.0",
         port=8090,
-        embed_task_processor=False,
-        services_config=None,
+        web_ui=False,
         **kwargs,
     ):
         """
-        Run the AgentApp using FastAPIAppFactory directly.
+        Launch the AgentApp HTTP API server.
+
+        This method starts a FastAPI server for the agent service.
+        Optionally, it can also launch a browser-based Web UI for
+        interacting with the agent.
+
+        Note:
+        If `web_ui=True` and this is the **first time** launching the Web UI,
+        additional time may be required to initialize. This happens because the
+        underlying Node.js command (`npx @agentscope-ai/chat
+        agentscope-runtime-webui`) might install dependencies and set up
+        the runtime environment.
 
         Args:
-            host: Host to bind to
-            port: Port to bind to
-            embed_task_processor: Whether to embed task processor
-            services_config: Optional services configuration
-            **kwargs: Additional keyword arguments
+            host (str): Host address to bind to. Default "0.0.0.0".
+            port (int): Port number to serve the application on. Default 8090.
+            web_ui (bool): If True, launches the Agentscope Web UI in a
+                separate process, pointing it to the API endpoint. This
+                allows interactive use via browser. Default False.
+            **kwargs: Additional keyword arguments passed to FastAPIAppFactory
+                when creating the FastAPI application.
+
+        Example:
+            >>> app = AgentApp(app_name="MyAgent")
+            >>> app.run(host="127.0.0.1", port=8000, web_ui=True)
         """
+        # Build runner
+        self._build_runner()
 
         try:
             logger.info(
                 "[AgentApp] Starting AgentApp with FastAPIAppFactory...",
             )
-
-            # Use default services config if not provided
-            if services_config is None:
-                services_config = DEFAULT_SERVICES_CONFIG
-
-            # Create FastAPI application using the factory
-            fastapi_app = FastAPIAppFactory.create_app(
-                runner=self._runner,
-                endpoint_path=self.endpoint_path,
-                request_model=self.request_model,
-                response_type=self.response_type,
-                stream=self.stream,
-                before_start=self.before_start,
-                after_finish=self.after_finish,
-                mode=DeploymentMode.DAEMON_THREAD,
-                services_config=services_config,
-                protocol_adapters=self.protocol_adapters,
-                custom_endpoints=self.custom_endpoints,
-                broker_url=self.broker_url,
-                backend_url=self.backend_url,
-                enable_embedded_worker=embed_task_processor,
-                **kwargs,
-            )
+            fastapi_app = self.get_fastapi_app(**kwargs)
 
             logger.info(f"[AgentApp] Starting server on {host}:{port}")
 
-            # Start the FastAPI application with uvicorn
-            uvicorn.run(
-                fastapi_app,
-                host=host,
-                port=port,
-                log_level="info",
-                access_log=True,
+            if web_ui:
+                webui_url = f"http://{host}:{port}{self.endpoint_path}"
+                cmd = (
+                    f"npx @agentscope-ai/chat agentscope-runtime-webui "
+                    f"--url {webui_url}"
+                )
+                logger.info(f"[AgentApp] WebUI started at {webui_url}")
+                logger.info(
+                    "[AgentApp] Note: First WebUI launch may take extra time "
+                    "as dependencies are installed.",
+                )
+                with subprocess.Popen(shlex.split(cmd)):
+                    uvicorn.run(
+                        fastapi_app,
+                        host=host,
+                        port=port,
+                        log_level="info",
+                        access_log=True,
+                    )
+            else:
+                uvicorn.run(
+                    fastapi_app,
+                    host=host,
+                    port=port,
+                    log_level="info",
+                    access_log=True,
+                )
+
+        except KeyboardInterrupt:
+            logger.info(
+                "[AgentApp] KeyboardInterrupt received, shutting down...",
             )
 
-        except Exception as e:
-            logger.error(f"[AgentApp] Error while running: {e}")
-            raise
+    def get_fastapi_app(self, **kwargs):
+        """Get the FastAPI application"""
+
+        self._build_runner()
+        mode = kwargs.pop("mode", DeploymentMode.DAEMON_THREAD)
+
+        return FastAPIAppFactory.create_app(
+            runner=self._runner,
+            endpoint_path=self.endpoint_path,
+            request_model=self.request_model,
+            response_type=self.response_type,
+            stream=self.stream,
+            before_start=self.before_start,
+            after_finish=self.after_finish,
+            mode=mode,
+            protocol_adapters=self.protocol_adapters,
+            custom_endpoints=self.custom_endpoints,
+            broker_url=self.broker_url,
+            backend_url=self.backend_url,
+            enable_embedded_worker=self.enable_embedded_worker,
+            app_kwargs=self._app_kwargs,
+            **kwargs,
+        )
 
-    async def deploy(self, deployer, **kwargs):
+    async def deploy(self, deployer: DeployManager, **kwargs):
         """Deploy the agent app with custom endpoints support"""
         # Pass custom endpoints and tasks to the deployer
+        # Build runner
+        self._build_runner()
 
         deploy_kwargs = {
-            **kwargs,
+            "app": self,
             "custom_endpoints": self.custom_endpoints,
-            "agent": self._agent,
             "runner": self._runner,
             "endpoint_path": self.endpoint_path,
             "stream": self.stream,
             "protocol_adapters": self.protocol_adapters,
         }
+        deploy_kwargs.update(kwargs)
         return await deployer.deploy(**deploy_kwargs)
 
     def endpoint(self, path: str, methods: Optional[List[str]] = None):

agentscope_runtime/engine/app/base_app.py

@@ -1,38 +1,29 @@
 # -*- coding: utf-8 -*-
 import inspect
 import logging
-import threading
 from typing import Callable, Optional
 
-import uvicorn
-from fastapi import FastAPI, Request
-from fastapi.responses import StreamingResponse
+from fastapi import Request
 
 from .celery_mixin import CeleryMixin
 
 logger = logging.getLogger(__name__)
 
 
-class BaseApp(FastAPI, CeleryMixin):
+class BaseApp(CeleryMixin):
     """
-    BaseApp extends FastAPI and integrates with Celery
-    for asynchronous background task execution.
+    BaseApp integrates Celery for asynchronous background task execution,
+    and provides FastAPI-like routing for task endpoints.
     """
 
     def __init__(
         self,
         broker_url: Optional[str] = None,
         backend_url: Optional[str] = None,
-        **kwargs,
     ):
         # Initialize CeleryMixin
         CeleryMixin.__init__(self, broker_url, backend_url)
 
-        self.server = None
-
-        # Initialize FastAPI
-        FastAPI.__init__(self, **kwargs)
-
     def task(self, path: str, queue: str = "celery"):
         """
         Register an asynchronous task endpoint.
@@ -74,108 +65,3 @@ class BaseApp(FastAPI, CeleryMixin):
             return func
 
         return decorator
-
-    def endpoint(self, path: str):
-        """
-        Unified POST endpoint decorator.
-        Pure FastAPI functionality, independent of Celery.
-        Supports:
-          - Sync functions
-          - Async functions (coroutines)
-          - Sync/async generator functions (streaming responses)
-        """
-
-        def decorator(func: Callable):
-            is_async_gen = inspect.isasyncgenfunction(func)
-            is_sync_gen = inspect.isgeneratorfunction(func)
-
-            if is_async_gen or is_sync_gen:
-                # Handle streaming responses
-                async def _stream_generator(request: Request):
-                    if is_async_gen:
-                        async for chunk in func(request):
-                            yield chunk
-                    else:
-                        for chunk in func(request):
-                            yield chunk
-
-                @self.post(path)
-                async def _wrapped(request: Request):
-                    return StreamingResponse(
-                        _stream_generator(request),
-                        media_type="text/plain",
-                    )
-
-            else:
-                # Handle regular responses
-                @self.post(path)
-                async def _wrapped(request: Request):
-                    if inspect.iscoroutinefunction(func):
-                        return await func(request)
-                    else:
-                        return func(request)
-
-            return func
-
-        return decorator
-
-    def run(
-        self,
-        host="0.0.0.0",
-        port=8090,
-        embed_task_processor=False,
-        **kwargs,
-    ):
-        """
-        Run FastAPI with uvicorn.
-        """
-        if embed_task_processor:
-            if self.celery_app is None:
-                logger.warning(
-                    "[AgentApp] Celery is not configured. "
-                    "Cannot run embedded worker.",
-                )
-            else:
-                logger.warning(
-                    "[AgentApp] embed_task_processor=True: Running "
-                    "task_processor in embedded thread mode. This is "
-                    "intended for development/debug purposes only. In "
-                    "production, run Celery worker in a separate process!",
-                )
-
-                queues = self._registered_queues or {"celery"}
-                queue_list = ",".join(sorted(queues))
-
-                def start_celery_worker():
-                    logger.info(
-                        f"[AgentApp] Embedded worker listening "
-                        f"queues: {queue_list}",
-                    )
-                    self.celery_app.worker_main(
-                        [
-                            "worker",
-                            "--loglevel=INFO",
-                            "-Q",
-                            queue_list,
-                        ],
-                    )
-
-                threading.Thread(
-                    target=start_celery_worker,
-                    daemon=True,
-                ).start()
-                logger.info(
-                    "[AgentApp] Embedded task processor started in background "
-                    "thread (DEV mode).",
-                )
-
-        # TODO: Add CLI to main entrypoint to control run/deploy
-
-        config = uvicorn.Config(
-            app=self,
-            host=host,
-            port=port,
-            **kwargs,
-        )
-        self.server = uvicorn.Server(config)
-        self.server.run()

agentscope_runtime/engine/constant.py

@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+ALLOWED_FRAMEWORK_TYPES = [
+    "text",
+    "agentscope",
+    "autogen",
+    "langgraph",
+    "agno",
+]

agentscope_runtime/engine/deployers/__init__.py

@@ -8,9 +8,17 @@ from .modelstudio_deployer import (
     ModelstudioDeployManager,
 )
 
+try:
+    from .agentrun_deployer import (
+        AgentRunDeployManager,
+    )
+except ImportError:
+    AgentRunDeployManager = None  # type: ignore
+
 __all__ = [
     "DeployManager",
     "LocalDeployManager",
     "KubernetesDeployManager",
     "ModelstudioDeployManager",
+    "AgentRunDeployManager",
 ]

agentscope_runtime/engine/deployers/adapter/__init__.py

@@ -0,0 +1,2 @@
+# -*- coding: utf-8 -*-
+from .a2a import A2AFastAPIDefaultAdapter