veadk-python 0.2.16__py3-none-any.whl → 0.2.17__py3-none-any.whl

veadk/cli/cli_deploy.py

@@ -62,7 +62,42 @@ def deploy(
     use_adk_web: bool,
     path: str,
 ) -> None:
-    """Deploy a user project to Volcengine FaaS application."""
+    """Deploy a user project to Volcengine FaaS application.
+
+    This command deploys a VeADK agent project to Volcengine's Function as a Service (FaaS)
+    platform. It creates a deployment package from the local project, configures the necessary
+    cloud resources, and manages the deployment process including template generation,
+    file copying, and cloud resource provisioning.
+
+    The deployment process includes:
+    1. Creating a temporary deployment package using cookiecutter templates
+    2. Copying the user's project files to the deployment structure
+    3. Processing configuration files and requirements
+    4. Executing the deployment to Volcengine FaaS
+    5. Cleaning up temporary files
+
+    Args:
+        access_key: Volcengine access key for API authentication. If not provided,
+            will use VOLCENGINE_ACCESS_KEY environment variable
+        secret_key: Volcengine secret key for API authentication. If not provided,
+            will use VOLCENGINE_SECRET_KEY environment variable
+        vefaas_app_name: Name of the target Volcengine FaaS application where the
+            project will be deployed
+        veapig_instance_name: Optional Volcengine API Gateway instance name for
+            external API access configuration
+        veapig_service_name: Optional Volcengine API Gateway service name
+        veapig_upstream_name: Optional Volcengine API Gateway upstream name
+        short_term_memory_backend: Backend type for short-term memory storage.
+            Choices are 'local' or 'mysql'
+        use_adk_web: Flag to enable ADK Web interface for the deployed agent
+        path: Local directory path containing the VeADK project to deploy
+
+    Note:
+        - The function automatically processes and copies requirements.txt if present in the project
+        - config.yaml files are excluded from deployment for security reasons
+        - Temporary files are created in /tmp and cleaned up after deployment
+        - The deployment uses cookiecutter templates for standardized project structure
+    """
     import asyncio
     import shutil
     from pathlib import Path

veadk/cli/cli_eval.py

@@ -64,6 +64,61 @@ def eval(
     volcengine_access_key: str,
     volcengine_secret_key: str,
 ) -> None:
+    """Evaluate an agent using specified evaluation datasets and metrics.
+
+    This command provides comprehensive agent evaluation capabilities using either Google ADK
+    or DeepEval frameworks. It supports both local agent evaluation (from source code) and
+    remote agent evaluation (via A2A deployment URLs), making it flexible for different
+    development and deployment scenarios.
+
+    The evaluation process includes:
+    1. Loading the target agent from local directory or remote A2A endpoint
+    2. Configuring the evaluation environment and credentials
+    3. Setting up the chosen evaluator with appropriate metrics
+    4. Running evaluation tests against the provided dataset
+    5. Generating detailed performance reports and scores
+
+    Evaluation Modes:
+    - Local Evaluation: Loads agent code from a local directory containing 'agent.py'
+      with exported 'root_agent' variable. Suitable for development and testing.
+    - Remote Evaluation: Connects to a deployed agent via A2A (Agent-to-Agent) URL.
+      Ideal for evaluating production deployments or distributed agents.
+
+    Evaluator Options:
+    - ADK Evaluator: Uses Google's Agent Development Kit evaluation framework.
+      Provides standardized metrics and comprehensive evaluation reports.
+    - DeepEval: Advanced evaluation framework with customizable metrics including
+      GEval for general performance and ToolCorrectnessMetric for tool usage accuracy.
+
+    Args:
+        agent_dir: Local directory path containing the agent implementation.
+            Must include an 'agent.py' file with exported 'root_agent' variable.
+            Defaults to current directory if not specified
+        agent_a2a_url: Complete URL of the deployed agent in A2A mode.
+            If provided alongside agent_dir, this URL takes precedence
+        evalset_file: Path to the evaluation dataset file in Google ADK format.
+            Should contain test cases with inputs, expected outputs, and metadata
+        evaluator: Evaluation framework to use. Available options:
+            - 'adk': Google ADK evaluator with built-in metrics
+            - 'deepeval': Advanced evaluator with customizable metrics and thresholds
+        judge_model_name: Name of the language model used for evaluation judgment.
+            Defaults to 'doubao-1-5-pro-256k-250115'. Only applicable for DeepEval;
+            ignored when using ADK evaluator
+        volcengine_access_key: Volcengine platform access key for model authentication.
+            If not provided, uses VOLCENGINE_ACCESS_KEY environment variable
+        volcengine_secret_key: Volcengine platform secret key for model authentication.
+            If not provided, uses VOLCENGINE_SECRET_KEY environment variable
+
+    Note:
+        - At least one of --agent-dir or --agent-a2a-url must be provided
+        - If both are provided, --agent-a2a-url takes precedence
+        - Judge model name is ignored when using ADK evaluator
+        - Evaluation results are logged and may be saved to output files
+
+    Raises:
+        ImportError: If DeepEval dependencies are not installed when using DeepEval evaluator.
+        ValueError: If neither agent_dir nor agent_a2a_url is provided.
+    """
     import asyncio
     import os
     from pathlib import Path

veadk/cli/cli_init.py

@@ -25,6 +25,14 @@ warnings.filterwarnings(
 
 
 def _render_prompts() -> dict[str, Any]:
+    """Render interactive prompts to collect user configuration for project initialization.
+
+    This function prompts the user for various configuration options including
+    Volcengine FaaS application name, API Gateway settings, and deployment mode.
+
+    Returns:
+        dict[str, Any]: A dictionary containing all the collected configuration values
+    """
     vefaas_application_name = click.prompt(
         "Volcengine FaaS application name", default="veadk-cloud-agent"
     )
@@ -71,9 +79,42 @@ def _render_prompts() -> dict[str, Any]:
 def init(
     vefaas_template_type: str,
 ) -> None:
-    """Init a veadk project that can be deployed to Volcengine VeFaaS.
-
-    `template` is A2A/MCP/Web server template, `web_template` is for web applications (i.e., a simple blog).
+    """Initialize a new VeADK project that can be deployed to Volcengine FaaS.
+
+    This command creates a new VeADK project from predefined templates using an interactive
+    setup process. It generates a complete project structure with all necessary files,
+    configurations, and deployment scripts ready for Volcengine cloud deployment.
+
+    The initialization process includes:
+    1. Interactive prompts for collecting deployment configuration
+    2. Template selection based on the specified template type
+    3. Project directory creation with proper structure
+    4. Configuration file generation with user preferences
+    5. Ready-to-use deployment scripts and source code structure
+
+    Available template types:
+    - 'template' (default): Creates an A2A/MCP/Web server template with a weather-reporter
+      example application. Suitable for most agent development scenarios.
+    - 'web_template': Creates a web application template with a simple-blog example.
+      Designed for web-based agent applications with UI components.
+
+    The generated project structure includes:
+    - src/ directory containing agent source code
+    - deploy.py script for cloud deployment
+    - Configuration files for various deployment scenarios
+    - Example implementations based on the selected template
+
+    Args:
+        vefaas_template_type: The type of template to use for project initialization.
+            Defaults to 'template'. Valid options are:
+            - 'template': Standard agent template (weather-reporter example)
+            - 'web_template': Web application template (simple-blog example)
+
+    Note:
+        - If the target directory already exists, you will be prompted to confirm overwrite
+        - The generated project includes example code that can be modified for your use case
+        - All deployment configurations can be customized after project creation
+        - The deploy.py script provides automated deployment to Volcengine FaaS platform
     """
     import shutil
     from pathlib import Path

veadk/cli/cli_kb.py

@@ -48,7 +48,42 @@ def add(
     index: str,
     path: str,
 ):
-    """Add files to knowledgebase"""
+    """Add files to knowledgebase.
+
+    This command adds files or directories to a specified knowledgebase backend.
+    It supports various backend types including local storage, OpenSearch, Viking,
+    and Redis for storing and indexing knowledge content.
+
+    Args:
+        backend: The knowledgebase backend type to use for storing and indexing documents.
+            Available options:
+            - 'local': Local file-based storage using SQLite. Suitable for development
+              and small-scale deployments. No external dependencies required.
+            - 'opensearch': Elasticsearch-compatible search engine with advanced
+              full-text search and vector similarity capabilities. Recommended for
+              production environments with large document collections.
+            - 'viking': Volcengine's managed vector database service optimized for
+              semantic search and RAG applications. Provides high performance and
+              automatic scaling on Volcengine cloud platform.
+            - 'redis': In-memory data structure store with vector search capabilities.
+              Fast retrieval but limited by memory capacity. Good for frequently
+              accessed, smaller knowledge bases.
+        app_name: Application identifier for organizing and isolating knowledgebase
+            data. Used to create logical separation between different applications
+            or environments. Must be consistent across operations for the same knowledge base.
+        index: Knowledgebase index identifier within the application namespace.
+            Acts as a unique name for this specific knowledge collection. Multiple
+            indexes can exist under the same app_name for different knowledge domains.
+            Index names should be descriptive and follow naming conventions of the chosen backend.
+        path: File system path to the knowledge content to be added to the knowledge base.
+            Supported formats:
+            - Single file: Path to a specific document (PDF, TXT, MD, DOCX, etc.)
+            - Directory: Path to a folder containing multiple documents. All supported
+              files in the directory will be processed recursively.
+
+    Raises:
+        RuntimeError: If the file type is not supported
+    """
     _path = Path(path)
     assert _path.exists(), f"Path {path} not exists. Please check your input."
 

veadk/cli/cli_pipeline.py

@@ -37,6 +37,18 @@ warnings.filterwarnings(
 
 
 def _create_cr(volcengine_settings: dict[str, str], cr_settings: dict[str, str]):
+    """Create Container Registry (CR) resources including instance, namespace, and repository.
+
+    This helper function creates the necessary Container Registry infrastructure
+    on Volcengine cloud platform for storing Docker images used in the CI/CD pipeline.
+
+    Args:
+        volcengine_settings: Dictionary containing Volcengine credentials and region
+        cr_settings: Dictionary containing CR instance, namespace, and repo configuration
+
+    Raises:
+        Exception: If any of the CR resource creation operations fail
+    """
     vecr = VeCR(
         access_key=volcengine_settings["volcengine_access_key"],
         secret_key=volcengine_settings["volcengine_secret_key"],
@@ -137,7 +149,60 @@ def pipeline(
     cr_repo_name: str,
     vefaas_function_id: str,
 ) -> None:
-    """Integrate a veadk project to volcengine pipeline for CI/CD"""
+    """Integrate a VeADK project with Volcengine pipeline for automated CI/CD deployment.
+
+    This command sets up a complete CI/CD pipeline that automatically builds, containerizes,
+    and deploys your VeADK agent project whenever changes are pushed to the specified GitHub
+    repository. It creates all necessary cloud infrastructure including Container Registry
+    resources, FaaS functions, and pipeline configurations.
+
+    The pipeline integration process includes:
+    1. Creating Container Registry (CR) infrastructure (instance, namespace, repository)
+    2. Setting up or using existing VeFaaS function for deployment target
+    3. Configuring Volcengine Code Pipeline with GitHub integration
+    4. Establishing automated build and deployment workflows
+    5. Linking all components for seamless CI/CD operation
+
+    Pipeline Workflow:
+    - Code changes pushed to GitHub trigger the pipeline
+    - Source code is automatically pulled from the specified branch
+    - Docker image is built using the specified VeADK base image
+    - Built image is pushed to Volcengine Container Registry
+    - VeFaaS function is updated with the new container image
+    - Deployment completion notifications are provided
+
+    Args:
+        veadk_version: Base VeADK image version for containerization. Can be:
+            - 'preview': Latest preview/development version
+            - 'latest': Latest stable release
+            - Specific version (e.g., '1.0.0'): Pinned version for consistency
+        github_url: Complete GitHub repository URL containing your VeADK project.
+            Must be accessible with the provided GitHub token
+        github_branch: Target branch to monitor for changes and deploy from.
+            Typically 'main', 'master', or your preferred deployment branch
+        github_token: GitHub personal access token with repository access permissions.
+            Required for pipeline to access and monitor your repository
+        volcengine_access_key: Volcengine cloud platform access key for authentication.
+            If not provided, uses VOLCENGINE_ACCESS_KEY environment variable
+        volcengine_secret_key: Volcengine cloud platform secret key for authentication.
+            If not provided, uses VOLCENGINE_SECRET_KEY environment variable
+        region: Volcengine cloud region for all resources (VeFaaS, CR, Pipeline).
+            Defaults to 'cn-beijing'. Choose region closest to your users
+        cr_instance_name: Name for the Container Registry instance that will store
+            your Docker images. Defaults to 'veadk-user-instance'
+        cr_namespace_name: Namespace within the Container Registry for organizing
+            repositories. Defaults to 'veadk-user-namespace'
+        cr_repo_name: Repository name within the Container Registry namespace
+            for storing your project images. Defaults to 'veadk-user-repo'
+        vefaas_function_id: Existing VeFaaS function ID to update with new deployments.
+            If not provided, a new function will be created automatically
+
+    Note:
+        - GitHub token must have appropriate permissions for repository access
+        - All Volcengine resources will be created in the specified region
+        - The pipeline will be triggered immediately upon creation for initial deployment
+        - Subsequent deployments occur automatically when code is pushed to the monitored branch
+    """
 
     click.echo(
         "Welcome use VeADK to integrate your project to volcengine pipeline for CI/CD."

veadk/cli/cli_prompt.py

@@ -30,7 +30,22 @@ import click
 def prompt(
     path: str, feedback: str, api_key: str, workspace_id: str, model_name: str
 ) -> None:
-    """Optimize agent system prompt from a local file."""
+    """Optimize agent system prompt from a local file.
+
+    This command uses Volcengine PromptPilot service to optimize agent system prompts
+    based on feedback and best practices. It loads agents from a specified file and
+    applies intelligent prompt optimization using the specified model.
+
+    Args:
+        path: Path to the agent file containing global variable `agent=...`
+        feedback: User feedback and suggestions for prompt optimization
+        api_key: API key for accessing PromptPilot service
+        workspace_id: Workspace ID in PromptPilot for organizing prompts
+        model_name: Name of the model to use for prompt optimization
+
+    Raises:
+        ValueError: If workspace_id is not provided when required
+    """
     from pathlib import Path
 
     from veadk.agent import Agent

veadk/cli/cli_uploadevalset.py

@@ -37,7 +37,21 @@ def uploadevalset(
     cozeloop_evalset_id: str,
     cozeloop_api_key: str,
 ) -> None:
-    """Upload dataset items to CozeLoop evaluation set."""
+    """Upload dataset items to CozeLoop evaluation set.
+
+    This command uploads evaluation dataset items from a JSON file to the CozeLoop
+    platform for agent evaluation and testing. It processes Google ADK formatted
+    evaluation cases and converts them to CozeLoop's expected format.
+
+    Args:
+        file: Path to the JSON file containing dataset items in Google ADK format.
+        cozeloop_workspace_id: CozeLoop workspace identifier for organizing evaluation sets.
+            If not provided, uses OBSERVABILITY_OPENTELEMETRY_COZELOOP_SERVICE_NAME environment variable.
+        cozeloop_evalset_id: Specific evaluation set ID where items will be uploaded.
+            If not provided, uses OBSERVABILITY_OPENTELEMETRY_COZELOOP_EVALSET_ID environment variable.
+        cozeloop_api_key: API key for authenticating with CozeLoop services.
+            If not provided, uses OBSERVABILITY_OPENTELEMETRY_COZELOOP_API_KEY environment variable.
+    """
 
     if not cozeloop_workspace_id:
         cozeloop_workspace_id = getenv(

veadk/cli/cli_web.py

@@ -23,7 +23,14 @@ logger = get_logger(__name__)
 
 def patch_adkwebserver_disable_openapi():
     """
-    Monkey patch AdkWebServer.get_fast_api to remove openapi.json route.
+    Monkey patch AdkWebServer to disable OpenAPI documentation endpoints.
+
+    This function patches the AdkWebServer.get_fast_api_app method to remove
+    OpenAPI-related routes (/openapi.json, /docs, /redoc) from the FastAPI
+    application for security and simplicity purposes.
+
+    The patch is applied by replacing the original method with a wrapped version
+    that filters out the unwanted routes after the FastAPI app is created.
     """
     import google.adk.cli.adk_web_server
     from fastapi.routing import APIRoute
@@ -52,7 +59,25 @@ def patch_adkwebserver_disable_openapi():
 )
 @click.pass_context
 def web(ctx, *args, **kwargs) -> None:
-    """Launch web with long term and short term memory."""
+    """
+    Launch a web server with VeADK agent support and memory integration.
+
+    This command starts a web server that can serve VeADK agents with both
+    short-term and long-term memory capabilities. It automatically detects
+    the type of agent being loaded and configures the appropriate memory
+    services accordingly.
+
+    The function patches the ADK web server to integrate VeADK-specific
+    functionality, including memory service configuration and workflow
+    agent detection.
+
+    Args:
+        ctx: Click context object containing command line arguments
+
+    Note:
+        For workflow agents (Sequential, Loop, Parallel), individual sub-agent
+        memory configurations are not utilized as warned in the logs.
+    """
     from google.adk.cli import adk_web_server
     from google.adk.runners import Runner as ADKRunner
 
@@ -107,6 +132,12 @@ def web(ctx, *args, **kwargs) -> None:
 
     from google.adk.cli.cli_tools_click import cli_web
 
-    extra_args = ctx.args
-    logger.debug(f"User args: {ctx.args}")
+    extra_args: list = ctx.args
+    logger.debug(f"User args: {extra_args}")
+
+    # set a default log level to avoid unnecessary outputs
+    # from Google ADK and Litellm
+    if "--log_level" not in extra_args:
+        extra_args.extend(["--log_level", "ERROR"])
+
     cli_web.main(args=extra_args, standalone_mode=False)

veadk/cloud/cloud_agent_engine.py

@@ -22,7 +22,7 @@ from typing import Any
 from pydantic import BaseModel
 
 from veadk.cloud.cloud_app import CloudApp
-from veadk.config import getenv
+from veadk.config import getenv, veadk_environments
 from veadk.integrations.ve_faas.ve_faas import VeFaaS
 from veadk.utils.logger import get_logger
 from veadk.utils.misc import formatted_timestamp
@@ -31,11 +31,51 @@ logger = get_logger(__name__)
 
 
 class CloudAgentEngine(BaseModel):
+    """Manages cloud agent deployment and operations on Volcengine FaaS platform.
+
+    This class handles authentication with Volcengine, deploys local projects to FaaS,
+    updates function code, removes applications, and supports local testing.
+
+    Attributes:
+        volcengine_access_key (str): Access key for Volcengine authentication.
+            Defaults to VOLCENGINE_ACCESS_KEY environment variable.
+        volcengine_secret_key (str): Secret key for Volcengine authentication.
+            Defaults to VOLCENGINE_SECRET_KEY environment variable.
+        region (str): Region for Volcengine services. Defaults to "cn-beijing".
+        _vefaas_service (VeFaaS): Internal VeFaaS client instance, initialized post-creation.
+
+    Note:
+        Credentials must be set via environment variables for default behavior.
+        This class performs interactive confirmations for destructive operations like removal.
+
+    Examples:
+        ```python
+        from veadk.cloud.cloud_agent_engine import CloudAgentEngine
+        engine = CloudAgentEngine()
+        app = engine.deploy("test-app", "/path/to/local/project")
+        print(app.vefaas_endpoint)
+        ```
+    """
+
     volcengine_access_key: str = getenv("VOLCENGINE_ACCESS_KEY")
     volcengine_secret_key: str = getenv("VOLCENGINE_SECRET_KEY")
     region: str = "cn-beijing"
 
     def model_post_init(self, context: Any, /) -> None:
+        """Initializes the internal VeFaaS service after Pydantic model validation.
+
+        Creates a VeFaaS instance using the configured access key, secret key, and region.
+
+        Args:
+            self: The CloudAgentEngine instance.
+            context: Pydantic post-init context parameter (not used).
+
+        Returns:
+            None
+
+        Note:
+            This is a Pydantic lifecycle method, ensuring service readiness after init.
+        """
         self._vefaas_service = VeFaaS(
             access_key=self.volcengine_access_key,
             secret_key=self.volcengine_secret_key,
@@ -43,6 +83,25 @@ class CloudAgentEngine(BaseModel):
         )
 
     def _prepare(self, path: str, name: str):
+        """Prepares the local project for deployment by validating path and name.
+
+        Checks if the path exists and is a directory, validates application name format.
+
+        Args:
+            path (str): Full or relative path to the local agent project directory.
+            name (str): Intended VeFaaS application name.
+
+        Returns:
+            None
+
+        Raises:
+            AssertionError: If path does not exist or is not a directory.
+            ValueError: If name contains invalid characters like underscores.
+
+        Note:
+            Includes commented code for handling requirements.txt; not executed currently.
+            Called internally by deploy and update methods.
+        """
         # basic check
         assert os.path.exists(path), f"Local agent project path `{path}` not exists."
         assert os.path.isdir(path), (
@@ -73,10 +132,23 @@ class CloudAgentEngine(BaseModel):
         #     )
 
     def _try_launch_fastapi_server(self, path: str):
-        """Try to launch a fastapi server for tests according to user's configuration.
+        """Tries to start a FastAPI server locally for testing deployment readiness.
+
+        Runs the project's run.sh script and checks connectivity on port 8000.
 
         Args:
-            path (str): Local agent project path.
+            path (str): Path to the local project containing run.sh.
+
+        Returns:
+            None
+
+        Raises:
+            RuntimeError: If server startup times out after 30 seconds.
+
+        Note:
+            Sets _FAAS_FUNC_TIMEOUT environment to 900 seconds.
+            Streams output to console and terminates process after successful check.
+            Assumes run.sh launches server on 0.0.0.0:8000.
         """
         RUN_SH = f"{path}/run.sh"
 
@@ -128,33 +200,42 @@ class CloudAgentEngine(BaseModel):
         use_adk_web: bool = False,
         local_test: bool = False,
     ) -> CloudApp:
-        """Deploy local agent project to Volcengine FaaS platform.
+        """Deploys a local agent project to Volcengine FaaS, creating necessary resources.
+
+        Prepares project, optionally tests locally, deploys via VeFaaS, and returns app instance.
 
         Args:
-            application_name (str): Expected VeFaaS application name.
-            path (str): Local agent project path.
-            gateway_name (str): Gateway name.
-            gateway_service_name (str): Gateway service name.
-            gateway_upstream_name (str): Gateway upstream name.
-            use_adk_web (bool): Whether to use ADK Web.
-            local_test (bool): Whether to run local test for FastAPI Server.
+            application_name (str): Unique name for the VeFaaS application.
+            path (str): Local directory path of the agent project.
+            gateway_name (str, optional): Custom gateway resource name. Defaults to timestamped.
+            gateway_service_name (str, optional): Custom service name. Defaults to timestamped.
+            gateway_upstream_name (str, optional): Custom upstream name. Defaults to timestamped.
+            use_adk_web (bool): Enable ADK Web configuration. Defaults to False.
+            local_test (bool): Perform FastAPI server test before deploy. Defaults to False.
 
         Returns:
-            CloudApp: The deployed cloud application instance.
+            CloudApp: Deployed application with endpoint, name, and ID.
+
+        Raises:
+            ValueError: On deployment failure, such as invalid config or VeFaaS errors.
+
+        Note:
+            Converts path to absolute; sets telemetry opt-out and ADK Web env vars.
+            Generates default gateway names if not specified.
+
+        Examples:
+            ```python
+            app = engine.deploy("my-agent", "./agent-project", local_test=True)
+            print(f"Deployed at: {app.vefaas_endpoint}")
+            ```
         """
         # prevent deepeval writing operations
-        import veadk.config
-
-        veadk.config.veadk_environments["DEEPEVAL_TELEMETRY_OPT_OUT"] = "YES"
+        veadk_environments["DEEPEVAL_TELEMETRY_OPT_OUT"] = "YES"
 
         if use_adk_web:
-            import veadk.config
-
-            veadk.config.veadk_environments["USE_ADK_WEB"] = "True"
+            veadk_environments["USE_ADK_WEB"] = "True"
         else:
-            import veadk.config
-
-            veadk.config.veadk_environments["USE_ADK_WEB"] = "False"
+            veadk_environments["USE_ADK_WEB"] = "False"
 
         # convert `path` to absolute path
         path = str(Path(path).resolve())
@@ -191,6 +272,28 @@ class CloudAgentEngine(BaseModel):
             )
 
     def remove(self, app_name: str):
+        """Deletes a deployed cloud application after user confirmation.
+
+        Locates app by name, confirms, and issues delete via VeFaaS.
+
+        Args:
+            app_name (str): Name of the application to remove.
+
+        Returns:
+            None
+
+        Raises:
+            ValueError: If application not found by name.
+
+        Note:
+            Interactive prompt required; cancels on non-'y' input.
+            Deletion is processed asynchronously by VeFaaS.
+
+        Examples:
+            ```python
+            engine.remove("my-agent")
+            ```
+        """
         confirm = input(f"Confirm delete cloud app {app_name}? (y/N): ")
         if confirm.lower() != "y":
             print("Delete cancelled.")
@@ -208,14 +311,28 @@ class CloudAgentEngine(BaseModel):
         application_name: str,
         path: str,
     ) -> CloudApp:
-        """Update existing agent project code while keeping the same URL.
+        """Updates the code in an existing VeFaaS application without changing endpoint.
+
+        Prepares new code from local path and updates function via VeFaaS.
 
         Args:
-            application_name (str): Existing application name to update.
-            path (str): Local agent project path.
+            application_name (str): Name of the existing application to update.
+            path (str): Local path containing updated project files.
 
         Returns:
-            CloudApp: Updated cloud app with same endpoint.
+            CloudApp: Updated application instance with same endpoint.
+
+        Raises:
+            ValueError: If update fails due to preparation or VeFaaS issues.
+
+        Note:
+            Preserves gateway and other resources; only function code is updated.
+            Path is resolved to absolute before processing.
+
+        Examples:
+            ```python
+            updated_app = engine.update_function_code("my-agent", "./updated-project")
+            ```
         """
         # convert `path` to absolute path
         path = str(Path(path).resolve())