veadk-python 0.2.1__py3-none-any.whl → 0.2.2__py3-none-any.whl

veadk/__init__.py

@@ -12,17 +12,23 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from .version import VERSION
+from typing import TYPE_CHECKING
+
+from veadk.version import VERSION
+
+if TYPE_CHECKING:
+    from veadk.agent import Agent
+    from veadk.runner import Runner
 
 
 # Lazy loading for `Agent` class
 def __getattr__(name):
     if name == "Agent":
-        from .agent import Agent
+        from veadk.agent import Agent
 
         return Agent
     if name == "Runner":
-        from .runner import Runner
+        from veadk.runner import Runner
 
         return Runner
     raise AttributeError(f"module 'veadk' has no attribute '{name}'")

veadk/a2a/remote_ve_agent.py

@@ -18,7 +18,7 @@ import requests
 from a2a.types import AgentCard
 from google.adk.agents.remote_a2a_agent import RemoteA2aAgent
 
-AGENT_CARD_WELL_KNOWN_PATH = "/.well-known/agent.json"
+AGENT_CARD_WELL_KNOWN_PATH = "/.well-known/agent-card.json"
 
 
 class RemoteVeAgent(RemoteA2aAgent):

veadk/a2a/ve_a2a_server.py

@@ -48,8 +48,6 @@ class VeA2AServer:
         )
         app = app_application.build()  # build routes
 
-        # import uvicorn
-        # uvicorn.run(app, host="127.0.0.1", port=8000)
         return app
 
 

veadk/agent.py

@@ -17,6 +17,7 @@ from __future__ import annotations
 from typing import Optional
 
 from google.adk.agents import LlmAgent, RunConfig
+from google.adk.agents.base_agent import BaseAgent
 from google.adk.agents.llm_agent import ToolUnion
 from google.adk.agents.run_config import StreamingMode
 from google.adk.models.lite_llm import LiteLlm
@@ -39,7 +40,6 @@ from veadk.prompts.agent_default_prompt import DEFAULT_DESCRIPTION, DEFAULT_INST
 from veadk.tracing.base_tracer import BaseTracer
 from veadk.utils.logger import get_logger
 from veadk.utils.patches import patch_asyncio
-from google.adk.agents.base_agent import BaseAgent
 
 patch_asyncio()
 logger = get_logger(__name__)
@@ -70,9 +70,7 @@ class Agent(LlmAgent):
     model_api_base: str = getenv("MODEL_AGENT_API_BASE", DEFAULT_MODEL_AGENT_API_BASE)
     """The api base of the model for agent running."""
 
-    model_api_key: str = Field(
-        ..., default_factory=lambda: getenv("MODEL_AGENT_API_KEY")
-    )
+    model_api_key: str = Field(default_factory=lambda: getenv("MODEL_AGENT_API_KEY"))
     """The api key of the model for agent running."""
 
     tools: list[ToolUnion] = []
@@ -244,8 +242,13 @@ class Agent(LlmAgent):
                 user_id=user_id,
                 session_id=session_id,
             )
-            await self.long_term_memory.add_session_to_memory(session)
-            logger.info(f"Add session `{session.id}` to your long-term memory.")
+            if session:
+                await self.long_term_memory.add_session_to_memory(session)
+                logger.info(f"Add session `{session.id}` to your long-term memory.")
+            else:
+                logger.error(
+                    f"Session {session_id} not found in session service, cannot save to long-term memory."
+                )
 
         if collect_runtime_data:
             eval_set_recorder = EvalSetRecorder(session_service, eval_set_id)
@@ -254,6 +257,6 @@ class Agent(LlmAgent):
 
         if self.tracers:
             for tracer in self.tracers:
-                tracer.dump(user_id, session_id)
+                tracer.dump(user_id=user_id, session_id=session_id)
 
         return final_output

veadk/cli/{services/agentpilot/__init__.py → cli.py}

@@ -12,6 +12,29 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from .agentpilot import AgentPilot
 
-__all__ = ["AgentPilot"]
+import click
+
+from veadk.cli.cli_deploy import deploy
+from veadk.cli.cli_init import init
+from veadk.cli.cli_prompt import prompt
+from veadk.cli.cli_web import web
+from veadk.version import VERSION
+
+
+@click.group()
+@click.version_option(
+    version=VERSION, prog_name="Volcengine Agent Development Kit (VeADK)"
+)
+def veadk():
+    """Volcengine ADK command line tools"""
+    pass
+
+
+veadk.add_command(deploy)
+veadk.add_command(init)
+veadk.add_command(prompt)
+veadk.add_command(web)
+
+if __name__ == "__main__":
+    veadk()

veadk/cli/cli_deploy.py

@@ -0,0 +1,147 @@
+# 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 click
+
+TEMP_PATH = "/tmp"
+
+
+@click.command()
+@click.option(
+    "--access-key",
+    default=None,
+    help="Volcengine access key",
+)
+@click.option(
+    "--secret-key",
+    default=None,
+    help="Volcengine secret key",
+)
+@click.option("--vefaas-app-name", help="Expected Volcengine FaaS application name")
+@click.option(
+    "--veapig-instance-name", default="", help="Expected Volcengine APIG instance name"
+)
+@click.option(
+    "--veapig-service-name", default="", help="Expected Volcengine APIG service name"
+)
+@click.option(
+    "--veapig-upstream-name", default="", help="Expected Volcengine APIG upstream name"
+)
+@click.option(
+    "--short-term-memory-backend",
+    default="local",
+    type=click.Choice(["local", "mysql"]),
+    help="Backend for short-term memory",
+)
+@click.option("--use-adk-web", is_flag=True, help="Whether to use ADK Web")
+@click.option("--path", default=".", help="Local project path")
+def deploy(
+    access_key: str,
+    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,
+    path: str,
+) -> None:
+    """Deploy a user project to Volcengine FaaS application."""
+    import asyncio
+    import shutil
+    from pathlib import Path
+
+    from cookiecutter.main import cookiecutter
+
+    import veadk.integrations.ve_faas as vefaas
+    from veadk.config import getenv
+    from veadk.utils.logger import get_logger
+    from veadk.utils.misc import formatted_timestamp, load_module_from_file
+
+    logger = get_logger(__name__)
+
+    if not access_key:
+        access_key = getenv("VOLCENGINE_ACCESS_KEY")
+    if not secret_key:
+        secret_key = getenv("VOLCENGINE_SECRET_KEY")
+
+    user_proj_abs_path = Path(path).resolve()
+    template_dir_path = Path(vefaas.__file__).parent / "template"
+
+    tmp_dir_name = f"{user_proj_abs_path.name}_{formatted_timestamp()}"
+
+    settings = {
+        "local_dir_name": tmp_dir_name,
+        "app_name": user_proj_abs_path.name,
+        "agent_module_name": user_proj_abs_path.name,
+        "short_term_memory_backend": short_term_memory_backend,
+        "vefaas_application_name": vefaas_app_name,
+        "veapig_instance_name": veapig_instance_name,
+        "veapig_service_name": veapig_service_name,
+        "veapig_upstream_name": veapig_upstream_name,
+        "use_adk_web": use_adk_web,
+    }
+
+    cookiecutter(
+        template=str(template_dir_path),
+        output_dir=TEMP_PATH,
+        no_input=True,
+        extra_context=settings,
+    )
+    logger.debug(f"Create a template project at {TEMP_PATH}/{tmp_dir_name}")
+
+    agent_dir = (
+        Path(TEMP_PATH)
+        / tmp_dir_name
+        / "src"
+        / user_proj_abs_path.name.replace("-", "_")
+    )
+
+    # remove /tmp/tmp_dir_name/src/user_proj_abs_path.name
+    shutil.rmtree(agent_dir)
+    agent_dir.mkdir(parents=True, exist_ok=True)
+
+    # copy
+    shutil.copytree(user_proj_abs_path, agent_dir, dirs_exist_ok=True)
+    logger.debug(f"Remove agent module from {user_proj_abs_path} to {agent_dir}")
+
+    # copy requirements.txt
+    if (user_proj_abs_path / "requirements.txt").exists():
+        logger.debug(
+            f"Find a requirements.txt in {user_proj_abs_path}/requirements.txt, copy it to temp project."
+        )
+        shutil.copy(
+            user_proj_abs_path / "requirements.txt",
+            Path(TEMP_PATH) / tmp_dir_name / "src" / "requirements.txt",
+        )
+    else:
+        logger.warning(
+            "No requirements.txt found in the user project, we will use a default one."
+        )
+
+    # load
+    logger.debug(
+        f"Load deploy module from {Path(TEMP_PATH) / tmp_dir_name / 'deploy.py'}"
+    )
+    deploy_module = load_module_from_file(
+        module_name="deploy_module",
+        file_path=str(Path(TEMP_PATH) / tmp_dir_name / "deploy.py"),
+    )
+    logger.info(f"Begin deploy from {Path(TEMP_PATH) / tmp_dir_name / 'src'}")
+    asyncio.run(deploy_module.main())
+
+    # remove tmp file
+    logger.info("Deploy done. Delete temp dir.")
+    shutil.rmtree(Path(TEMP_PATH) / tmp_dir_name)

veadk/cli/cli_init.py

@@ -0,0 +1,106 @@
+# 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 warnings
+from typing import Any
+
+import click
+
+warnings.filterwarnings(
+    "ignore", category=UserWarning, module="pydantic._internal._fields"
+)
+
+
+def _render_prompts() -> dict[str, Any]:
+    vefaas_application_name = click.prompt(
+        "Volcengine FaaS application name", default="veadk-cloud-agent"
+    )
+
+    veapig_instance_name = click.prompt(
+        "Volcengine API Gateway instance name", default="", show_default=True
+    )
+
+    veapig_service_name = click.prompt(
+        "Volcengine API Gateway service name", default="", show_default=True
+    )
+
+    veapig_upstream_name = click.prompt(
+        "Volcengine API Gateway upstream name", default="", show_default=True
+    )
+
+    deploy_mode_options = {
+        "1": "A2A/MCP Server",
+        "2": "VeADK Web / Google ADK Web",
+    }
+
+    click.echo("Choose a deploy mode:")
+    for key, value in deploy_mode_options.items():
+        click.echo(f"  {key}. {value}")
+
+    deploy_mode = click.prompt(
+        "Enter your choice", type=click.Choice(deploy_mode_options.keys())
+    )
+
+    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",
+    }
+
+
+@click.command()
+def init() -> None:
+    """Init a veadk project that can be deployed to Volcengine VeFaaS."""
+    import shutil
+    from pathlib import Path
+
+    from cookiecutter.main import cookiecutter
+
+    import veadk.integrations.ve_faas as vefaas
+
+    click.echo(
+        "Welcome use VeADK to create your project. We will generate a `weather-reporter` application for you."
+    )
+
+    cwd = Path.cwd()
+    local_dir_name = click.prompt("Local directory name", default="veadk-cloud-proj")
+    target_dir_path = cwd / local_dir_name
+
+    if target_dir_path.exists():
+        click.confirm(
+            f"Directory '{target_dir_path}' already exists, do you want to overwrite it",
+            abort=True,
+        )
+        shutil.rmtree(target_dir_path)
+
+    settings = _render_prompts()
+    settings["local_dir_name"] = local_dir_name
+
+    template_dir_path = Path(vefaas.__file__).parent / "template"
+
+    cookiecutter(
+        template=str(template_dir_path),
+        output_dir=str(cwd),
+        extra_context=settings,
+        no_input=True,
+    )
+
+    click.echo(f"Template project has been generated at {target_dir_path}")
+    click.echo(f"Edit {target_dir_path / 'src/'} to define your agents")
+    click.echo(
+        f"Edit {target_dir_path / 'deploy.py'} to define your deployment attributes"
+    )
+    click.echo("Run python `deploy.py` for deployment on Volcengine FaaS platform.")

veadk/cli/cli_prompt.py

@@ -0,0 +1,64 @@
+# 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 click
+
+
+@click.command()
+@click.option(
+    "--path", default=".", help="Agent file path with global variable `agent=...`"
+)
+@click.option("--feedback", default=None, help="Suggestions for prompt optimization")
+@click.option("--api-key", default=None, help="API Key of PromptPilot")
+@click.option(
+    "--model-name",
+    default="doubao-1.5-pro-32k-250115",
+    help="Model name for prompt optimization",
+)
+def prompt(path: str, feedback: str, api_key: str, model_name: str) -> None:
+    """Optimize agent system prompt from a local file."""
+    from pathlib import Path
+
+    from veadk.agent import Agent
+    from veadk.config import getenv
+    from veadk.integrations.ve_prompt_pilot.ve_prompt_pilot import VePromptPilot
+    from veadk.utils.misc import load_module_from_file
+
+    module_name = "agents_for_prompt_pilot"
+    module_abs_path = Path(path).resolve()
+
+    module = load_module_from_file(
+        module_name=module_name, file_path=str(module_abs_path)
+    )
+
+    # get all global variables from module
+    globals_in_module = vars(module)
+
+    agents = []
+    for global_variable_name, global_variable_value in globals_in_module.items():
+        if isinstance(global_variable_value, Agent):
+            agent = global_variable_value
+            agents.append(agent)
+
+    if len(agents) > 0:
+        click.echo(f"Found {len(agents)} agents in {module_abs_path}")
+
+        if not api_key:
+            api_key = getenv("PROMPT_PILOT_API_KEY")
+        ve_prompt_pilot = VePromptPilot(api_key)
+        ve_prompt_pilot.optimize(
+            agents=agents, feedback=feedback, model_name=model_name
+        )
+    else:
+        click.echo(f"No agents found in {module_abs_path}")

veadk/cli/cli_web.py

@@ -0,0 +1,154 @@
+# 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 click
+
+from veadk.memory.long_term_memory import LongTermMemory
+from veadk.memory.short_term_memory import ShortTermMemory
+
+
+def _get_stm_from_module(module) -> ShortTermMemory:
+    return module.agent_run_config.short_term_memory
+
+
+def _get_stm_from_env() -> ShortTermMemory:
+    import os
+
+    from veadk.utils.logger import get_logger
+
+    logger = get_logger(__name__)
+
+    short_term_memory_backend = os.getenv("SHORT_TERM_MEMORY_BACKEND")
+    if not short_term_memory_backend:  # prevent None or empty string
+        short_term_memory_backend = "local"
+    logger.info(f"Short term memory: backend={short_term_memory_backend}")
+
+    return ShortTermMemory(backend=short_term_memory_backend)  # type: ignore
+
+
+def _get_ltm_from_module(module) -> LongTermMemory | None:
+    agent = module.agent_run_config.agent
+
+    if not hasattr(agent, "long_term_memory"):
+        return None
+    else:
+        return agent.long_term_memory
+
+
+def _get_ltm_from_env() -> LongTermMemory | None:
+    import os
+
+    from veadk.utils.logger import get_logger
+
+    logger = get_logger(__name__)
+
+    long_term_memory_backend = os.getenv("LONG_TERM_MEMORY_BACKEND")
+
+    if long_term_memory_backend:
+        logger.info(f"Long term memory: backend={long_term_memory_backend}")
+        return LongTermMemory(backend=long_term_memory_backend)  # type: ignore
+    else:
+        logger.warning("No long term memory backend settings detected.")
+        return None
+
+
+def _get_memory(
+    module_path: str,
+) -> tuple[ShortTermMemory, LongTermMemory | None]:
+    from veadk.utils.logger import get_logger
+    from veadk.utils.misc import load_module_from_file
+
+    logger = get_logger(__name__)
+
+    # 1. load user module
+    try:
+        module_file_path = module_path
+        module = load_module_from_file(
+            module_name="agent_and_mem", file_path=f"{module_file_path}/agent.py"
+        )
+    except Exception as e:
+        logger.error(
+            f"Failed to get memory config from `agent.py`: {e}. Fallback to get memory from environment variables."
+        )
+        return _get_stm_from_env(), _get_ltm_from_env()
+
+    if not hasattr(module, "agent_run_config"):
+        logger.error(
+            "You must export `agent_run_config` as a global variable in `agent.py`. Fallback to get memory from environment variables."
+        )
+        return _get_stm_from_env(), _get_ltm_from_env()
+
+    # 2. try to get short term memory
+    # short term memory must exist in user code, as we use `default_factory` to init it
+    short_term_memory = _get_stm_from_module(module)
+
+    # 3. try to get long term memory
+    long_term_memory = _get_ltm_from_module(module)
+    if not long_term_memory:
+        long_term_memory = _get_ltm_from_env()
+
+    return short_term_memory, long_term_memory
+
+
+@click.command()
+@click.option("--host", default="127.0.0.1", help="Host to run the web server on")
+def web(host: str) -> None:
+    """Launch web with long term and short term memory."""
+    import os
+    from typing import Any
+
+    from google.adk.cli.utils.shared_value import SharedValue
+
+    from veadk.utils.logger import get_logger
+
+    logger = get_logger(__name__)
+
+    def init_for_veadk(
+        self,
+        *,
+        agent_loader: Any,
+        session_service: Any,
+        memory_service: Any,
+        artifact_service: Any,
+        credential_service: Any,
+        eval_sets_manager: Any,
+        eval_set_results_manager: Any,
+        agents_dir: str,
+    ):
+        self.agent_loader = agent_loader
+        self.artifact_service = artifact_service
+        self.credential_service = credential_service
+        self.eval_sets_manager = eval_sets_manager
+        self.eval_set_results_manager = eval_set_results_manager
+        self.agents_dir = agents_dir
+        self.runners_to_clean = set()
+        self.current_app_name_ref = SharedValue(value="")
+        self.runner_dict = {}
+
+        # parse VeADK memories
+        short_term_memory, long_term_memory = _get_memory(module_path=agents_dir)
+        self.session_service = short_term_memory.session_service
+        self.memory_service = long_term_memory
+
+    import google.adk.cli.adk_web_server
+
+    google.adk.cli.adk_web_server.AdkWebServer.__init__ = init_for_veadk
+
+    import google.adk.cli.cli_tools_click as cli_tools_click
+
+    agents_dir = os.getcwd()
+    logger.info(f"Load agents from {agents_dir}")
+
+    cli_tools_click.cli_web.main(args=[agents_dir, "--host", host])