veadk-python 0.2.21__tar.gz → 0.2.23__tar.gz

{veadk_python-0.2.21 → veadk_python-0.2.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: veadk-python
-Version: 0.2.21
+Version: 0.2.23
 Summary: Volcengine agent development kit, integrations with Volcengine cloud services.
 Author-email: Yaozheng Fang <fangyozheng@gmail.com>, Guodong Li <cu.eric.lee@gmail.com>, Zhi Han <sliverydayday@gmail.com>, Meng Wang <mengwangwm@gmail.com>
 License:                                  Apache License
@@ -218,7 +218,7 @@ Requires-Dist: opentelemetry-exporter-otlp>=1.35.0
 Requires-Dist: opentelemetry-instrumentation-logging>=0.56b0
 Requires-Dist: wrapt>=1.17.2
 Requires-Dist: openai<1.100
-Requires-Dist: volcengine-python-sdk>=4.0.18
+Requires-Dist: volcengine-python-sdk>=4.0.33
 Requires-Dist: volcengine>=1.0.193
 Requires-Dist: agent-pilot-sdk>=0.1.2
 Requires-Dist: fastmcp>=2.11.3

{veadk_python-0.2.21 → veadk_python-0.2.23}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "veadk-python"
-version = "0.2.21"
+version = "0.2.23"
 description = "Volcengine agent development kit, integrations with Volcengine cloud services."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -22,7 +22,7 @@ dependencies = [
     "opentelemetry-instrumentation-logging>=0.56b0",
     "wrapt>=1.17.2", # For patching built-in functions
     "openai<1.100", # For fix https://github.com/BerriAI/litellm/issues/13710
-    "volcengine-python-sdk>=4.0.18", # For Volcengine API
+    "volcengine-python-sdk>=4.0.33", # For Volcengine API
     "volcengine>=1.0.193", # For Volcengine sign
     "agent-pilot-sdk>=0.1.2", # Prompt optimization by Volcengine AgentPilot/PromptPilot toolkits
     "fastmcp>=2.11.3", # For running MCP

{veadk_python-0.2.21 → veadk_python-0.2.23}/tests/test_cloud.py

@@ -61,6 +61,12 @@ async def test_cloud():
                 mock_vefaas_service.find_app_id_by_name.return_value = "app-123"
                 mock_vefaas_service.delete.return_value = None
 
+                mock_vefaas_service.get_application_route.return_value = (
+                    "gw-123",
+                    "svc-456",
+                    "route-789",
+                )
+
                 # Test CloudAgentEngine creation and deploy functionality
                 engine = CloudAgentEngine()
 

veadk_python-0.2.23/veadk/a2a/remote_ve_agent.py

@@ -0,0 +1,198 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import json
+from typing import Literal, Optional
+
+import httpx
+import requests
+from a2a.types import AgentCard
+from google.adk.agents.remote_a2a_agent import RemoteA2aAgent
+
+from veadk.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+AGENT_CARD_WELL_KNOWN_PATH = "/.well-known/agent-card.json"
+
+
+def _convert_agent_card_dict_to_obj(agent_card_dict: dict) -> AgentCard:
+    agent_card_json_str = json.dumps(agent_card_dict, ensure_ascii=False, indent=2)
+    agent_card_object = AgentCard.model_validate_json(str(agent_card_json_str))
+    return agent_card_object
+
+
+class RemoteVeAgent(RemoteA2aAgent):
+    """Connect to a remote agent on the VeFaaS platform.
+
+    This class provides an interface to remotely connect with an agent deployed on the
+    VeFaaS platform. It automatically fetches the agent card (metadata) and configures
+    an HTTP client for secure communication.
+
+    The class extends `RemoteA2aAgent` to provide compatibility with the A2A
+    (Agent-to-Agent) communication layer.
+
+    This constructor handles agent discovery and HTTP client setup. It determines the
+    agent's URL, fetches its metadata (`agent_card`), and prepares an
+    `httpx.AsyncClient` for subsequent communication. You can either provide a URL
+    directly, or pass a pre-configured `httpx.AsyncClient` with a `base_url`.
+
+    Authentication can be handled via a bearer token in the HTTP header or via a
+    query string parameter. If a custom `httpx_client` is provided, authentication
+    details will be added to it.
+
+    Attributes:
+        name (str):
+            A unique name identifying this remote agent instance.
+        url (Optional[str]):
+            The base URL of the remote agent. This is optional if an `httpx_client`
+            with a configured `base_url` is provided. If both are given, they must
+            not conflict.
+        auth_token (Optional[str]):
+            Optional authentication token used for secure access. If not provided,
+            the agent will be accessed without authentication.
+        auth_method (Literal["header", "querystring"] | None):
+            The method of attaching the authentication token.
+            - `"header"`: Token is passed via HTTP `Authorization` header.
+            - `"querystring"`: Token is passed as a query parameter.
+        httpx_client (Optional[httpx.AsyncClient]):
+            An optional, pre-configured `httpx.AsyncClient` to use for communication.
+            This allows for client sharing and advanced configurations (e.g., proxies).
+            If its `base_url` is set, it will be used as the agent's location.
+
+    Raises:
+        ValueError:
+            - If `url` and `httpx_client.base_url` are both provided and conflict.
+            - If neither `url` nor an `httpx_client` with a `base_url` is provided.
+            - If an unsupported `auth_method` is provided when `auth_token` is set.
+        requests.RequestException:
+            If fetching the agent card from the remote URL fails.
+
+    Examples:
+        ```python
+        # Example 1: Connect using a URL
+        agent = RemoteVeAgent(
+            name="public_agent",
+            url="https://vefaas.example.com/agents/public"
+        )
+
+        # Example 2: Using Bearer token in header
+        agent = RemoteVeAgent(
+            name="secured_agent",
+            url="https://vefaas.example.com/agents/secure",
+            auth_token="my_secret_token",
+            auth_method="header"
+        )
+
+        # Example 3: Using a pre-configured httpx_client
+        import httpx
+        client = httpx.AsyncClient(
+            base_url="https://vefaas.example.com/agents/query",
+            timeout=600
+        )
+        agent = RemoteVeAgent(
+            name="query_agent",
+            auth_token="my_secret_token",
+            auth_method="querystring",
+            httpx_client=client
+        )
+        ```
+    """
+
+    def __init__(
+        self,
+        name: str,
+        url: Optional[str] = None,
+        auth_token: Optional[str] = None,
+        auth_method: Literal["header", "querystring"] | None = None,
+        httpx_client: Optional[httpx.AsyncClient] = None,
+    ):
+        # Determine the effective URL for the agent and handle conflicts.
+        effective_url = url
+        if httpx_client and httpx_client.base_url:
+            client_url_str = str(httpx_client.base_url).rstrip("/")
+            if url and url.rstrip("/") != client_url_str:
+                raise ValueError(
+                    f"The `url` parameter ('{url}') conflicts with the `base_url` of the provided "
+                    f"httpx_client ('{client_url_str}'). Please provide only one or ensure they match."
+                )
+            effective_url = client_url_str
+
+        if not effective_url:
+            raise ValueError(
+                "Could not determine agent URL. Please provide the `url` parameter or an `httpx_client` with a configured `base_url`."
+            )
+
+        req_headers = {}
+        req_params = {}
+
+        if auth_token:
+            if auth_method == "header":
+                req_headers = {"Authorization": f"Bearer {auth_token}"}
+            elif auth_method == "querystring":
+                req_params = {"token": auth_token}
+            elif auth_method:
+                raise ValueError(
+                    f"Unsupported auth method {auth_method}, use `header` or `querystring` instead."
+                )
+
+        agent_card_dict = requests.get(
+            effective_url + AGENT_CARD_WELL_KNOWN_PATH,
+            headers=req_headers,
+            params=req_params,
+        ).json()
+        # replace agent_card_url with actual host
+        agent_card_dict["url"] = effective_url
+
+        agent_card_object = _convert_agent_card_dict_to_obj(agent_card_dict)
+
+        logger.debug(f"Agent card of {name}: {agent_card_object}")
+
+        client_was_provided = httpx_client is not None
+        client_to_use = httpx_client
+
+        if client_was_provided:
+            # If a client was provided, update it with auth info
+            if auth_token:
+                if auth_method == "header":
+                    client_to_use.headers.update(req_headers)
+                elif auth_method == "querystring":
+                    new_params = dict(client_to_use.params)
+                    new_params.update(req_params)
+                    client_to_use.params = new_params
+        else:
+            # If no client was provided, create a new one with auth info
+            if auth_token:
+                if auth_method == "header":
+                    client_to_use = httpx.AsyncClient(
+                        base_url=effective_url, headers=req_headers, timeout=600
+                    )
+                elif auth_method == "querystring":
+                    client_to_use = httpx.AsyncClient(
+                        base_url=effective_url, params=req_params, timeout=600
+                    )
+            else:  # No auth, no client provided
+                client_to_use = httpx.AsyncClient(base_url=effective_url, timeout=600)
+
+        super().__init__(
+            name=name, agent_card=agent_card_object, httpx_client=client_to_use
+        )
+
+        # The parent class sets _httpx_client_needs_cleanup based on whether
+        # the httpx_client it received was None. Since we always pass a
+        # client (either the user's or one we create), it will always set
+        # it to False. We must override this to ensure clients we create
+        # are properly cleaned up.
+        if not client_was_provided:
+            self._httpx_client_needs_cleanup = True

{veadk_python-0.2.21 → veadk_python-0.2.23}/veadk/a2a/ve_a2a_server.py

@@ -35,6 +35,7 @@ class VeA2AServer:
             runner=Runner(
                 agent=agent,
                 app_name=app_name,
+                short_term_memory=short_term_memory,
             ),
         )
 

{veadk_python-0.2.21 → veadk_python-0.2.23}/veadk/agent.py

@@ -123,6 +123,8 @@ class Agent(LlmAgent):
         )
     """
 
+    enable_authz: bool = False
+
     def model_post_init(self, __context: Any) -> None:
         super().model_post_init(None)  # for sub_agents init
 
@@ -184,6 +186,22 @@ class Agent(LlmAgent):
                 load_memory.custom_metadata["backend"] = self.long_term_memory.backend
             self.tools.append(load_memory)
 
+        if self.enable_authz:
+            from veadk.tools.builtin_tools.agent_authorization import (
+                check_agent_authorization,
+            )
+
+            if self.before_agent_callback:
+                if isinstance(self.before_agent_callback, list):
+                    self.before_agent_callback.append(check_agent_authorization)
+                else:
+                    self.before_agent_callback = [
+                        self.before_agent_callback,
+                        check_agent_authorization,
+                    ]
+            else:
+                self.before_agent_callback = check_agent_authorization
+
         logger.info(f"VeADK version: {VERSION}")
 
         logger.info(f"{self.__class__.__name__} `{self.name}` init done.")

{veadk_python-0.2.21 → veadk_python-0.2.23}/veadk/cli/cli_clean.py

@@ -24,7 +24,7 @@ logger = get_logger(__name__)
 
 @click.command()
 @click.option(
-    "--vefaas-application-name",
+    "--vefaas-app-name",
     required=True,
     help="VeFaaS application name to clean",
 )
@@ -39,7 +39,7 @@ logger = get_logger(__name__)
     help="Volcengine secret key, if not set, will use the value of environment variable VOLCENGINE_SECRET_KEY",
 )
 def clean(
-    vefaas_application_name: str, volcengine_access_key: str, volcengine_secret_key: str
+    vefaas_app_name: str, volcengine_access_key: str, volcengine_secret_key: str
 ) -> None:
     """
     Clean and delete a VeFaaS application from the cloud.
@@ -49,7 +49,7 @@ def clean(
     and monitor the deletion process until completion.
 
     Args:
-        vefaas_application_name (str): The name of the VeFaaS application to delete
+        vefaas_app_name (str): The name of the VeFaaS application to delete
         volcengine_access_key (str): Volcengine access key for authentication.
             If None, will use VOLCENGINE_ACCESS_KEY environment variable
         volcengine_secret_key (str): Volcengine secret key for authentication.
@@ -63,7 +63,7 @@ def clean(
     if not volcengine_secret_key:
         volcengine_secret_key = getenv("VOLCENGINE_SECRET_KEY")
 
-    confirm = input(f"Confirm delete cloud app {vefaas_application_name}? (y/N): ")
+    confirm = input(f"Confirm delete cloud app {vefaas_app_name}? (y/N): ")
     if confirm.lower() != "y":
         click.echo("Delete cancelled.")
         return
@@ -71,16 +71,14 @@ def clean(
         vefaas_client = VeFaaS(
             access_key=volcengine_access_key, secret_key=volcengine_secret_key
         )
-        vefaas_application_id = vefaas_client.find_app_id_by_name(
-            vefaas_application_name
-        )
+        vefaas_application_id = vefaas_client.find_app_id_by_name(vefaas_app_name)
         vefaas_client.delete(vefaas_application_id)
         click.echo(
-            f"Cloud app {vefaas_application_name} delete request has been sent to VeFaaS"
+            f"Cloud app {vefaas_app_name} delete request has been sent to VeFaaS"
         )
         while True:
             try:
-                id = vefaas_client.find_app_id_by_name(vefaas_application_name)
+                id = vefaas_client.find_app_id_by_name(vefaas_app_name)
                 if not id:
                     break
                 time.sleep(3)

{veadk_python-0.2.21 → veadk_python-0.2.23}/veadk/cli/cli_deploy.py

@@ -22,12 +22,12 @@ TEMP_PATH = "/tmp"
 
 @click.command()
 @click.option(
-    "--access-key",
+    "--volcengine-access-key",
     default=None,
     help="Volcengine access key",
 )
 @click.option(
-    "--secret-key",
+    "--volcengine-secret-key",
     default=None,
     help="Volcengine secret key",
 )
@@ -50,16 +50,35 @@ TEMP_PATH = "/tmp"
     help="Backend for short-term memory",
 )
 @click.option("--use-adk-web", is_flag=True, help="Whether to use ADK Web")
+@click.option(
+    "--auth-method",
+    default="none",
+    type=click.Choice(["none", "api-key", "oauth2"]),
+    help="=Authentication method for agent",
+)
+@click.option(
+    "--user-pool-name",
+    default="",
+    help="Expected Volcengine Identity user pool name",
+)
+@click.option(
+    "--client-name",
+    default="",
+    help="Expected Volcengine Identity client name",
+)
 @click.option("--path", default=".", help="Local project path")
 def deploy(
-    access_key: str,
-    secret_key: str,
+    volcengine_access_key: str,
+    volcengine_secret_key: str,
     vefaas_app_name: str,
     veapig_instance_name: str,
     veapig_service_name: str,
     veapig_upstream_name: str,
     short_term_memory_backend: str,
     use_adk_web: bool,
+    auth_method: str,
+    user_pool_name: str,
+    client_name: str,
     path: str,
 ) -> None:
     """Deploy a user project to Volcengine FaaS application.
@@ -77,9 +96,9 @@ def deploy(
     5. Cleaning up temporary files
 
     Args:
-        access_key: Volcengine access key for API authentication. If not provided,
+        volcengine_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,
+        volcengine_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
@@ -90,6 +109,10 @@ def deploy(
         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
+        auth_method: Authentication for the agent.
+            Choices are 'none', 'api-key' or 'oauth2'.
+        veidentity_user_pool_name: Optional Volcengine Identity user pool name
+        veidentity_client_name: Optional Volcengine Identity client name
         path: Local directory path containing the VeADK project to deploy
 
     Note:
@@ -111,10 +134,10 @@ def deploy(
 
     logger = get_logger(__name__)
 
-    if not access_key:
-        access_key = getenv("VOLCENGINE_ACCESS_KEY")
-    if not secret_key:
-        secret_key = getenv("VOLCENGINE_SECRET_KEY")
+    if not volcengine_access_key:
+        volcengine_access_key = getenv("VOLCENGINE_ACCESS_KEY")
+    if not volcengine_secret_key:
+        volcengine_secret_key = getenv("VOLCENGINE_SECRET_KEY")
 
     user_proj_abs_path = Path(path).resolve()
     template_dir_path = Path(vefaas.__file__).parent / "template"
@@ -131,6 +154,9 @@ def deploy(
         "veapig_service_name": veapig_service_name,
         "veapig_upstream_name": veapig_upstream_name,
         "use_adk_web": use_adk_web,
+        "auth_method": auth_method,
+        "veidentity_user_pool_name": user_pool_name,
+        "veidentity_client_name": client_name,
         "veadk_version": VERSION,
     }
 

{veadk_python-0.2.21 → veadk_python-0.2.23}/veadk/cli/cli_init.py

@@ -61,13 +61,49 @@ def _render_prompts() -> dict[str, Any]:
     deploy_mode = click.prompt(
         "Enter your choice", type=click.Choice(deploy_mode_options.keys())
     )
+    use_adk_web = deploy_mode == "2"
+
+    auth_method_options = {
+        "1": "None",
+        "2": "API key",
+        "3": "OAuth2",
+    }
+    auth_methods = {
+        "1": "none",
+        "2": "api-key",
+        "3": "oauth2",
+    }
+
+    click.echo("Choose an authentication method:")
+    for key, value in auth_method_options.items():
+        click.echo(f"  {key}. {value}")
+
+    auth_method_idx = click.prompt(
+        "Enter your choice", type=click.Choice(auth_method_options.keys())
+    )
+    auth_method = auth_methods[auth_method_idx]
+
+    veidentity_user_pool_name = ""
+    veidentity_client_name = ""
+    if auth_method == "oauth2":
+        veidentity_user_pool_name = click.prompt(
+            "Volcengine Identity user pool name", default="", show_default=True
+        )
+
+        if use_adk_web:
+            veidentity_client_name = click.prompt(
+                "Volcengine Identity client name", default="", show_default=True
+            )
 
     return {
         "vefaas_application_name": vefaas_application_name,
         "veapig_instance_name": veapig_instance_name,
         "veapig_service_name": veapig_service_name,
         "veapig_upstream_name": veapig_upstream_name,
-        "use_adk_web": deploy_mode == "2",
+        "use_adk_web": use_adk_web,
+        "auth_method": auth_method,
+        "veidentity_user_pool_name": veidentity_user_pool_name,
+        "veidentity_client_name": veidentity_client_name,
         "veadk_version": VERSION,
     }
 

{veadk_python-0.2.21 → veadk_python-0.2.23}/veadk/cli/cli_update.py

@@ -13,10 +13,10 @@
 # limitations under the License.
 
 import click
-import os
 
 from veadk.cloud.cloud_agent_engine import CloudAgentEngine
 from veadk.utils.logger import get_logger
+from veadk.config import getenv
 
 logger = get_logger(__name__)
 
@@ -33,7 +33,7 @@ logger = get_logger(__name__)
     help="Volcengine secret key for authentication. Defaults to VOLCENGINE_SECRET_KEY environment variable.",
 )
 @click.option(
-    "--application-name",
+    "--vefaas-app-name",
     required=True,
     help="Name of the cloud application to update.",
 )
@@ -45,7 +45,7 @@ logger = get_logger(__name__)
 def update(
     volcengine_access_key: str,
     volcengine_secret_key: str,
-    application_name: str,
+    vefaas_app_name: str,
     path: str,
 ) -> None:
     """Update function code of a deployed cloud application on Volcengine FaaS.
@@ -65,7 +65,7 @@ def update(
             If not provided, uses VOLCENGINE_ACCESS_KEY environment variable.
         volcengine_secret_key: Volcengine platform secret key for authentication.
             If not provided, uses VOLCENGINE_SECRET_KEY environment variable.
-        application_name: Name of the existing cloud application to update.
+        vefaas_app_name: Name of the existing cloud application to update.
         path: Local directory path containing the updated agent project.
             Defaults to current directory if not specified.
 
@@ -79,22 +79,25 @@ def update(
         FileNotFoundError: If local path does not exist.
     """
     # Set environment variables if provided
-    if volcengine_access_key and "VOLCENGINE_ACCESS_KEY" not in os.environ:
-        os.environ["VOLCENGINE_ACCESS_KEY"] = volcengine_access_key
-    if volcengine_secret_key and "VOLCENGINE_SECRET_KEY" not in os.environ:
-        os.environ["VOLCENGINE_SECRET_KEY"] = volcengine_secret_key
+    if not volcengine_access_key:
+        volcengine_access_key = getenv("VOLCENGINE_ACCESS_KEY")
+    if not volcengine_secret_key:
+        volcengine_secret_key = getenv("VOLCENGINE_SECRET_KEY")
 
     # Initialize cloud agent engine
-    engine = CloudAgentEngine()
+    engine = CloudAgentEngine(
+        volcengine_access_key=volcengine_access_key,
+        volcengine_secret_key=volcengine_secret_key,
+    )
 
     try:
         # Update function code
         updated_app = engine.update_function_code(
-            application_name=application_name,
+            application_name=vefaas_app_name,
             path=path,
         )
 
-        logger.info(f"Successfully updated cloud application '{application_name}'")
+        logger.info(f"Successfully updated cloud application '{vefaas_app_name}'")
         logger.info(f"Endpoint: {updated_app.vefaas_endpoint}")
         logger.info(f"Application ID: {updated_app.vefaas_application_id}")