veadk-python 0.2.1__tar.gz → 0.2.2__tar.gz

{veadk_python-0.2.1/veadk_python.egg-info → veadk_python-0.2.2}/PKG-INFO

@@ -1,21 +1,22 @@
 Metadata-Version: 2.4
 Name: veadk-python
-Version: 0.2.1
+Version: 0.2.2
 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>
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pydantic-settings>=2.10.1
-Requires-Dist: a2a-sdk==0.2.12
+Requires-Dist: a2a-sdk>=0.3.0
 Requires-Dist: deprecated>=1.2.18
-Requires-Dist: google-adk==1.8.0
+Requires-Dist: google-adk>=1.10.0
 Requires-Dist: litellm>=1.74.3
 Requires-Dist: loguru>=0.7.3
 Requires-Dist: openinference-instrumentation-google-adk>=0.1.1
 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.99.9
 Provides-Extra: database
 Requires-Dist: opensearch-py==2.8.0; extra == "database"
 Requires-Dist: redis>=6.2.0; extra == "database"
@@ -28,9 +29,9 @@ Requires-Dist: deepeval>=3.2.6; extra == "eval"
 Requires-Dist: google-adk[eval]; extra == "eval"
 Provides-Extra: cli
 Requires-Dist: volcengine-python-sdk==4.0.3; extra == "cli"
-Requires-Dist: typer>=0.16.0; extra == "cli"
-Requires-Dist: streamlit==1.46.1; extra == "cli"
 Requires-Dist: agent-pilot-sdk>=0.0.9; extra == "cli"
+Requires-Dist: fastmcp>=2.11.3; extra == "cli"
+Requires-Dist: cookiecutter>=2.6.0; extra == "cli"
 Provides-Extra: dev
 Requires-Dist: pre-commit>=4.2.0; extra == "dev"
 Requires-Dist: pytest>=8.4.1; extra == "dev"
@@ -51,6 +52,8 @@ An open-source kit for agent development, integrated the powerful capabilities o
 
 For more details, see our [documents](https://volcengine.github.io/veadk-python/).
 
+A [tutorial](https://github.com/volcengine/veadk-python/blob/main/veadk_tutorial.ipynb) is available by Jupyter Notebook, or open it in [Google Colab](https://colab.research.google.com/github/volcengine/veadk-python/blob/main/veadk_tutorial.ipynb) directly.
+
 ## Installation
 
 We use `uv` to build this project ([how-to-install-uv](https://docs.astral.sh/uv/getting-started/installation/)).
@@ -128,6 +131,14 @@ Before commit or push your changes, please make sure the unittests are passed ,o
 pytest -n 16
 ```
 
+## Contact with us
+
+Join our discussion group by scanning the QR code below:
+
+<p align="center">
+    <img src="assets/images/veadk_group_qrcode.jpg" alt="Volcengine Agent Development Kit Logo" width="40%">
+</p>
+
 ## License
 
 This project is licensed under the [Apache 2.0 License](./LICENSE).

{veadk_python-0.2.1 → veadk_python-0.2.2}/README.md

@@ -11,6 +11,8 @@ An open-source kit for agent development, integrated the powerful capabilities o
 
 For more details, see our [documents](https://volcengine.github.io/veadk-python/).
 
+A [tutorial](https://github.com/volcengine/veadk-python/blob/main/veadk_tutorial.ipynb) is available by Jupyter Notebook, or open it in [Google Colab](https://colab.research.google.com/github/volcengine/veadk-python/blob/main/veadk_tutorial.ipynb) directly.
+
 ## Installation
 
 We use `uv` to build this project ([how-to-install-uv](https://docs.astral.sh/uv/getting-started/installation/)).
@@ -88,6 +90,14 @@ Before commit or push your changes, please make sure the unittests are passed ,o
 pytest -n 16
 ```
 
+## Contact with us
+
+Join our discussion group by scanning the QR code below:
+
+<p align="center">
+    <img src="assets/images/veadk_group_qrcode.jpg" alt="Volcengine Agent Development Kit Logo" width="40%">
+</p>
+
 ## License
 
 This project is licensed under the [Apache 2.0 License](./LICENSE).

{veadk_python-0.2.1 → veadk_python-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "veadk-python"
-version = "0.2.1"
+version = "0.2.2"
 description = "Volcengine agent development kit, integrations with Volcengine cloud services."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -12,19 +12,20 @@ authors = [
 ]
 dependencies = [
     "pydantic-settings>=2.10.1", # Config management
-    "a2a-sdk==0.2.12", # For Google Agent2Agent protocol
+    "a2a-sdk>=0.3.0", # For Google Agent2Agent protocol
     "deprecated>=1.2.18",
-    "google-adk==1.8.0", # For basic agent architecture
+    "google-adk>=1.10.0", # For basic agent architecture
     "litellm>=1.74.3", # For model inference
     "loguru>=0.7.3", # For better logging
     "openinference-instrumentation-google-adk>=0.1.1", # For OpenInference instrumentation
     "opentelemetry-exporter-otlp>=1.35.0",
     "opentelemetry-instrumentation-logging>=0.56b0",
     "wrapt>=1.17.2", # For patching built-in functions
+    "openai==1.99.9" # For fix https://github.com/BerriAI/litellm/issues/13710
 ]
 
 [project.scripts]
-veadk = "veadk.cli.main:app"
+veadk = "veadk.cli.cli:veadk"
 
 [project.optional-dependencies]
 database = [
@@ -41,9 +42,9 @@ eval = [
 ]
 cli = [
     "volcengine-python-sdk==4.0.3", # For Volcengine API
-    "typer>=0.16.0",                # For command-line implementation
-    "streamlit==1.46.1",            # For running VeADK studio app
-    "agent-pilot-sdk>=0.0.9"        # Prompt optimization by Volcengine AgentPilot/PromptPilot toolkits
+    "agent-pilot-sdk>=0.0.9",       # Prompt optimization by Volcengine AgentPilot/PromptPilot toolkits
+    "fastmcp>=2.11.3",              # For running MCP
+    "cookiecutter>=2.6.0", # For cloud deploy
 ]
 dev = [
     "pre-commit>=4.2.0",            # Format checking
@@ -70,4 +71,9 @@ exclude = ["assets*", "ide*", "tests*"]
 include-package-data = true
 
 [tool.setuptools.package-data]
-"veadk" = ["**/*"]
+"veadk" = ["**/*"]
+
+[tool.ruff]
+exclude = [
+    "veadk/integrations/ve_faas/template/*"
+]

{veadk_python-0.2.1 → veadk_python-0.2.2}/tests/test_cloud.py

@@ -14,9 +14,9 @@
 
 import os
 import tempfile
-import pytest
+from unittest.mock import AsyncMock, Mock, patch
 
-from unittest.mock import Mock, patch, AsyncMock
+import pytest
 
 os.environ["VOLCENGINE_ACCESS_KEY"] = "test_access_key"
 os.environ["VOLCENGINE_SECRET_KEY"] = "test_secret_key"
@@ -110,7 +110,7 @@ async def test_cloud():
                 # Test CloudApp delete_self functionality
                 with patch("builtins.input", return_value="y"):
                     with patch(
-                        "veadk.cli.services.vefaas.vefaas.VeFaaS"
+                        "veadk.integrations.ve_faas.ve_faas.VeFaaS"
                     ) as mock_vefaas_in_app:
                         mock_vefaas_client = Mock()
                         mock_vefaas_in_app.return_value = mock_vefaas_client

{veadk_python-0.2.1 → veadk_python-0.2.2}/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_python-0.2.1 → veadk_python-0.2.2}/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_python-0.2.1 → veadk_python-0.2.2}/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_python-0.2.1 → veadk_python-0.2.2}/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_python-0.2.1/veadk/utils/misc.py → veadk_python-0.2.2/veadk/cli/cli.py

@@ -12,22 +12,29 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import time
 
+import click
 
-def read_file(file_path):
-    with open(file_path, "r", encoding="utf-8") as f:
-        data = f.readlines()
-    data = [x.strip() for x in data]
-    return data
+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
 
 
-def formatted_timestamp():
-    # YYYYMMDDHHMMSS
-    return time.strftime("%Y%m%d%H%M%S", time.localtime())
+@click.group()
+@click.version_option(
+    version=VERSION, prog_name="Volcengine Agent Development Kit (VeADK)"
+)
+def veadk():
+    """Volcengine ADK command line tools"""
+    pass
 
 
-def read_png_to_bytes(png_path: str) -> bytes:
-    with open(png_path, "rb") as f:
-        data = f.read()
-    return data
+veadk.add_command(deploy)
+veadk.add_command(init)
+veadk.add_command(prompt)
+veadk.add_command(web)
+
+if __name__ == "__main__":
+    veadk()

veadk_python-0.2.2/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_python-0.2.2/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_python-0.2.2/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}")