veadk-python 0.2.5__py3-none-any.whl → 0.2.7__py3-none-any.whl

veadk/agent.py

@@ -14,11 +14,11 @@
 
 from __future__ import annotations
 
-from typing import Optional
+from typing import Optional, Union
 
 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.llm_agent import InstructionProvider, ToolUnion
 from google.adk.agents.run_config import StreamingMode
 from google.adk.models.lite_llm import LiteLlm
 from google.adk.runners import Runner
@@ -26,12 +26,10 @@ from google.genai import types
 from pydantic import ConfigDict, Field
 from typing_extensions import Any
 
-from veadk.config import getenv
+from veadk.config import settings
 from veadk.consts import (
-    DEFAULT_MODEL_AGENT_PROVIDER,
-    DEFAULT_MODEL_AGENT_API_BASE,
-    DEFAULT_MODEL_AGENT_NAME,
-    DEFAULT_MODEL_EXTRA_HEADERS,
+    DEFAULT_AGENT_NAME,
+    DEFAULT_MODEL_EXTRA_CONFIG,
 )
 from veadk.evaluation import EvalSetRecorder
 from veadk.knowledgebase import KnowledgeBase
@@ -53,25 +51,25 @@ class Agent(LlmAgent):
     model_config = ConfigDict(arbitrary_types_allowed=True, extra="allow")
     """The model config"""
 
-    name: str = "veAgent"
+    name: str = DEFAULT_AGENT_NAME
     """The name of the agent."""
 
     description: str = DEFAULT_DESCRIPTION
     """The description of the agent. This will be helpful in A2A scenario."""
 
-    instruction: str = DEFAULT_INSTRUCTION
-    """The instruction for the agent, such as principles of function calling."""
+    instruction: Union[str, InstructionProvider] = DEFAULT_INSTRUCTION
+    """The instruction for the agent."""
 
-    model_name: str = getenv("MODEL_AGENT_NAME", DEFAULT_MODEL_AGENT_NAME)
+    model_name: str = Field(default_factory=lambda: settings.model.name)
     """The name of the model for agent running."""
 
-    model_provider: str = getenv("MODEL_AGENT_PROVIDER", DEFAULT_MODEL_AGENT_PROVIDER)
+    model_provider: str = Field(default_factory=lambda: settings.model.provider)
     """The provider of the model for agent running."""
 
-    model_api_base: str = getenv("MODEL_AGENT_API_BASE", DEFAULT_MODEL_AGENT_API_BASE)
+    model_api_base: str = Field(default_factory=lambda: settings.model.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: settings.model.api_key)
     """The api key of the model for agent running."""
 
     model_extra_config: dict = Field(default_factory=dict)
@@ -95,17 +93,26 @@ class Agent(LlmAgent):
     tracers: list[BaseTracer] = []
     """The tracers provided to agent."""
 
-    serve_url: str = ""
-    """The url of agent serving host. Show in agent card."""
-
     def model_post_init(self, __context: Any) -> None:
         super().model_post_init(None)  # for sub_agents init
 
-        # add model request source (veadk) in extra headers
-        if self.model_extra_config and "extra_headers" in self.model_extra_config:
-            self.model_extra_config["extra_headers"] |= DEFAULT_MODEL_EXTRA_HEADERS
-        else:
-            self.model_extra_config["extra_headers"] = DEFAULT_MODEL_EXTRA_HEADERS
+        # combine user model config with VeADK defaults
+        headers = DEFAULT_MODEL_EXTRA_CONFIG["extra_headers"].copy()
+        body = DEFAULT_MODEL_EXTRA_CONFIG["extra_body"].copy()
+
+        if self.model_extra_config:
+            user_headers = self.model_extra_config.get("extra_headers", {})
+            user_body = self.model_extra_config.get("extra_body", {})
+
+            headers |= user_headers
+            body |= user_body
+
+        self.model_extra_config |= {
+            "extra_headers": headers,
+            "extra_body": body,
+        }
+
+        logger.info(f"Model extra config: {self.model_extra_config}")
 
         if not self.model:
             self.model = LiteLlm(

veadk/agent_builder.py

@@ -0,0 +1,94 @@
+# 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 importlib
+
+from google.adk.agents import BaseAgent
+from omegaconf import OmegaConf
+
+from veadk.a2a.remote_ve_agent import RemoteVeAgent
+from veadk.agent import Agent
+from veadk.agents.loop_agent import LoopAgent
+from veadk.agents.parallel_agent import ParallelAgent
+from veadk.agents.sequential_agent import SequentialAgent
+from veadk.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+AGENT_TYPES = {
+    "Agent": Agent,
+    "SequentialAgent": SequentialAgent,
+    "ParallelAgent": ParallelAgent,
+    "LoopAgent": LoopAgent,
+    "RemoteVeAgent": RemoteVeAgent,
+}
+
+
+class AgentBuilder:
+    def __init__(self) -> None:
+        pass
+
+    def _build(self, agent_config: dict) -> BaseAgent:
+        logger.info(f"Building agent with config: {agent_config}")
+
+        sub_agents = []
+        if agent_config.get("sub_agents", None):
+            for sub_agent_config in agent_config["sub_agents"]:
+                agent = self._build(sub_agent_config)
+                sub_agents.append(agent)
+            agent_config.pop("sub_agents")
+
+        tools = []
+        if agent_config.get("tools", []):
+            for tool in agent_config["tools"]:
+                module_name = tool["module"]
+                func_name = tool["func"]
+
+                module = importlib.import_module(module_name)
+                func = getattr(module, func_name)
+
+                tools.append(func)
+            agent_config.pop("tools")
+
+        agent_cls = AGENT_TYPES[agent_config["type"]]
+        agent = agent_cls(**agent_config, sub_agents=sub_agents, tools=tools)
+
+        logger.debug("Build agent done.")
+
+        return agent
+
+    def _read_config(self, path: str) -> dict:
+        """Read config file (from `path`) to a in-memory dict."""
+        assert path.endswith(".yaml"), "Agent config file must be a `.yaml` file."
+
+        config = OmegaConf.load(path)
+        config_dict = OmegaConf.to_container(config, resolve=True)
+
+        assert isinstance(config_dict, dict), (
+            "Parsed config must in `dict` format. Pls check your building file format."
+        )
+
+        return config_dict
+
+    def build(
+        self,
+        path: str,
+        root_agent_identifier: str = "root_agent",
+    ) -> BaseAgent:
+        config = self._read_config(path)
+
+        agent_config = config[root_agent_identifier]
+        agent = self._build(agent_config)
+
+        return agent

veadk/auth/__init__.py

@@ -0,0 +1,13 @@
+# 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.

veadk/auth/base_auth.py

@@ -0,0 +1,22 @@
+# 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.
+
+
+class BaseAuth:
+    def __init__(self) -> None: ...
+
+    def _fetch_token(self) -> str | dict: ...
+
+    @property
+    def token(self) -> str | dict: ...

veadk/auth/veauth/__init__.py

@@ -0,0 +1,13 @@
+# 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.

veadk/auth/veauth/apmplus_veauth.py

@@ -0,0 +1,65 @@
+# 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 os
+
+from typing_extensions import override
+
+from veadk.auth.veauth.base_veauth import BaseVeAuth
+from veadk.utils.logger import get_logger
+from veadk.utils.volcengine_sign import ve_request
+
+logger = get_logger(__name__)
+
+
+class APMPlusVeAuth(BaseVeAuth):
+    def __init__(
+        self,
+        access_key: str = os.getenv("VOLCENGINE_ACCESS_KEY", ""),
+        secret_key: str = os.getenv("VOLCENGINE_SECRET_KEY", ""),
+        region: str = "cn-beijing",
+    ) -> None:
+        super().__init__(access_key, secret_key)
+
+        self.region = region
+
+        self._token: str = ""
+
+    @override
+    def _fetch_token(self) -> None:
+        logger.info("Fetching APMPlus token...")
+
+        res = ve_request(
+            request_body={},
+            action="GetAppKey",
+            ak=self.access_key,
+            sk=self.secret_key,
+            service="apmplus_server",
+            version="2024-07-30",
+            region=self.region,
+            host="open.volcengineapi.com",
+            # APMPlus frontend required
+            header={"X-Apmplus-Region": self.region.replace("-", "_")},
+        )
+        try:
+            self._token = res["data"]["app_key"]
+        except KeyError:
+            raise ValueError(f"Failed to get APMPlus token: {res}")
+
+    @property
+    def token(self) -> str:
+        if self._token:
+            return self._token
+        self._fetch_token()
+        return self._token

veadk/auth/veauth/ark_veauth.py

@@ -0,0 +1,77 @@
+# 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 os
+
+from typing_extensions import override
+
+from veadk.auth.veauth.base_veauth import BaseVeAuth
+from veadk.utils.logger import get_logger
+from veadk.utils.volcengine_sign import ve_request
+
+logger = get_logger(__name__)
+
+
+class ARKVeAuth(BaseVeAuth):
+    def __init__(
+        self,
+        access_key: str = os.getenv("VOLCENGINE_ACCESS_KEY", ""),
+        secret_key: str = os.getenv("VOLCENGINE_SECRET_KEY", ""),
+    ) -> None:
+        super().__init__(access_key, secret_key)
+
+        self._token: str = ""
+
+    @override
+    def _fetch_token(self) -> None:
+        logger.info("Fetching ARK token...")
+        # list api keys
+        first_api_key_id = ""
+        res = ve_request(
+            request_body={"ProjectName": "default", "Filter": {}},
+            action="ListApiKeys",
+            ak=self.access_key,
+            sk=self.secret_key,
+            service="ark",
+            version="2024-01-01",
+            region="cn-beijing",
+            host="open.volcengineapi.com",
+        )
+        try:
+            first_api_key_id = res["Result"]["Items"][0]["Id"]
+        except KeyError:
+            raise ValueError(f"Failed to get ARK api key list: {res}")
+
+        # get raw api key
+        res = ve_request(
+            request_body={"Id": first_api_key_id},
+            action="GetRawApiKey",
+            ak=self.access_key,
+            sk=self.secret_key,
+            service="ark",
+            version="2024-01-01",
+            region="cn-beijing",
+            host="open.volcengineapi.com",
+        )
+        try:
+            self._token = res["Result"]["ApiKey"]
+        except KeyError:
+            raise ValueError(f"Failed to get ARK api key: {res}")
+
+    @property
+    def token(self) -> str:
+        if self._token:
+            return self._token
+        self._fetch_token()
+        return self._token

veadk/auth/veauth/base_veauth.py

@@ -0,0 +1,50 @@
+# 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 os
+from abc import ABC, abstractmethod
+
+from veadk.auth.base_auth import BaseAuth
+
+
+class BaseVeAuth(ABC, BaseAuth):
+    volcengine_access_key: str
+    """Volcengine Access Key"""
+
+    volcengine_secret_key: str
+    """Volcengine Secret Key"""
+
+    def __init__(
+        self,
+        access_key: str | None = None,
+        secret_key: str | None = None,
+    ) -> None:
+        super().__init__()
+
+        final_ak = access_key or os.getenv("VOLCENGINE_ACCESS_KEY")
+        final_sk = secret_key or os.getenv("VOLCENGINE_SECRET_KEY")
+
+        assert final_ak, "Volcengine access key cannot be empty."
+        assert final_sk, "Volcengine secret key cannot be empty."
+
+        self.access_key = final_ak
+        self.secret_key = final_sk
+
+        self._token: str = ""
+
+    @abstractmethod
+    def _fetch_token(self) -> None: ...
+
+    @property
+    def token(self) -> str: ...

veadk/auth/veauth/cozeloop_veauth.py

@@ -0,0 +1,13 @@
+# 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.

veadk/auth/veauth/prompt_pilot_veauth.py

@@ -0,0 +1,60 @@
+# 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 os
+
+from typing_extensions import override
+
+from veadk.auth.veauth.base_veauth import BaseVeAuth
+from veadk.utils.logger import get_logger
+from veadk.utils.volcengine_sign import ve_request
+
+logger = get_logger(__name__)
+
+
+class PromptPilotVeAuth(BaseVeAuth):
+    def __init__(
+        self,
+        access_key: str = os.getenv("VOLCENGINE_ACCESS_KEY", ""),
+        secret_key: str = os.getenv("VOLCENGINE_SECRET_KEY", ""),
+    ) -> None:
+        super().__init__(access_key, secret_key)
+
+        self._token: str = ""
+
+    @override
+    def _fetch_token(self) -> None:
+        logger.info("Fetching Prompt Pilot token...")
+
+        res = ve_request(
+            request_body={},
+            action="GetOrCreatePromptPilotAPIKeys",
+            ak=self.access_key,
+            sk=self.secret_key,
+            service="ark",
+            version="2024-01-01",
+            region="cn-beijing",
+            host="open.volcengineapi.com",
+        )
+        try:
+            self._token = res["Result"]["APIKeys"][0]["APIKey"]
+        except KeyError:
+            raise ValueError(f"Failed to get Prompt Pilot token: {res}")
+
+    @property
+    def token(self) -> str:
+        if self._token:
+            return self._token
+        self._fetch_token()
+        return self._token

veadk/auth/veauth/vesearch_veauth.py

@@ -0,0 +1,62 @@
+# 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 os
+
+from typing_extensions import override
+
+from veadk.auth.veauth.base_veauth import BaseVeAuth
+from veadk.utils.logger import get_logger
+from veadk.utils.volcengine_sign import ve_request
+
+logger = get_logger(__name__)
+
+
+class VesearchVeAuth(BaseVeAuth):
+    def __init__(
+        self,
+        access_key: str = os.getenv("VOLCENGINE_ACCESS_KEY", ""),
+        secret_key: str = os.getenv("VOLCENGINE_SECRET_KEY", ""),
+    ) -> None:
+        super().__init__(access_key, secret_key)
+
+        self._token: str = ""
+
+    @override
+    def _fetch_token(self):
+        logger.info("Fetching VeSearch token ...")
+
+        res = ve_request(
+            request_body={"biz_scene": "search_agent", "page": 1, "rows": 10},
+            action="ListAPIKeys",
+            ak=self.access_key,
+            sk=self.secret_key,
+            service="content_customization",
+            version="2025-01-01",
+            region="cn-beijing",
+            host="open.volcengineapi.com",
+        )
+        try:
+            self._token = res["Result"]["api_key_vos"][0]["api_key"]
+
+            logger.info("Fetching VeSearch token done.")
+        except KeyError:
+            raise ValueError(f"Failed to get VeSearch token: {res}")
+
+    @property
+    def token(self) -> str:
+        if self._token:
+            return self._token
+        self._fetch_token()
+        return self._token

veadk/cli/cli.py

@@ -19,6 +19,7 @@ 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.cli.cli_pipeline import pipeline
 from veadk.version import VERSION
 
 
@@ -35,6 +36,7 @@ veadk.add_command(deploy)
 veadk.add_command(init)
 veadk.add_command(prompt)
 veadk.add_command(web)
+veadk.add_command(pipeline)
 
 if __name__ == "__main__":
     veadk()

veadk/cli/cli_deploy.py

@@ -15,6 +15,8 @@
 
 import click
 
+from veadk.version import VERSION
+
 TEMP_PATH = "/tmp"
 
 
@@ -85,8 +87,8 @@ def deploy(
     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,
+        "local_dir_name": tmp_dir_name.replace("-", "_"),
+        "app_name": user_proj_abs_path.name.replace("-", "_"),
         "agent_module_name": user_proj_abs_path.name,
         "short_term_memory_backend": short_term_memory_backend,
         "vefaas_application_name": vefaas_app_name,
@@ -94,6 +96,7 @@ def deploy(
         "veapig_service_name": veapig_service_name,
         "veapig_upstream_name": veapig_upstream_name,
         "use_adk_web": use_adk_web,
+        "veadk_version": VERSION,
     }
 
     cookiecutter(

veadk/cli/cli_init.py

@@ -17,6 +17,8 @@ from typing import Any
 
 import click
 
+from veadk.version import VERSION
+
 warnings.filterwarnings(
     "ignore", category=UserWarning, module="pydantic._internal._fields"
 )
@@ -58,12 +60,21 @@ def _render_prompts() -> dict[str, Any]:
         "veapig_service_name": veapig_service_name,
         "veapig_upstream_name": veapig_upstream_name,
         "use_adk_web": deploy_mode == "2",
+        "veadk_version": VERSION,
     }
 
 
 @click.command()
-def init() -> None:
-    """Init a veadk project that can be deployed to Volcengine VeFaaS."""
+@click.option(
+    "--vefaas-template-type", default="template", help="Expected template type"
+)
+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).
+    """
     import shutil
     from pathlib import Path
 
@@ -71,9 +82,14 @@ def init() -> None:
 
     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."
-    )
+    if vefaas_template_type == "web_template":
+        click.echo(
+            "Welcome use VeADK to create your project. We will generate a `simple-blog` web application for you."
+        )
+    else:
+        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")
@@ -89,7 +105,10 @@ def init() -> None:
     settings = _render_prompts()
     settings["local_dir_name"] = local_dir_name
 
-    template_dir_path = Path(vefaas.__file__).parent / "template"
+    if not vefaas_template_type:
+        vefaas_template_type = "template"
+
+    template_dir_path = Path(vefaas.__file__).parent / vefaas_template_type
 
     cookiecutter(
         template=str(template_dir_path),