veadk-python 0.2.6__tar.gz → 0.2.7__tar.gz

{veadk_python-0.2.6 → veadk_python-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: veadk-python
-Version: 0.2.6
+Version: 0.2.7
 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
@@ -223,6 +223,7 @@ Requires-Dist: agent-pilot-sdk>=0.0.9
 Requires-Dist: fastmcp>=2.11.3
 Requires-Dist: cookiecutter>=2.6.0
 Requires-Dist: opensearch-py==2.8.0
+Requires-Dist: omegaconf>=2.3.0
 Provides-Extra: database
 Requires-Dist: redis>=6.2.0; extra == "database"
 Requires-Dist: pymysql>=1.1.1; extra == "database"

{veadk_python-0.2.6 → veadk_python-0.2.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "veadk-python"
-version = "0.2.6"
+version = "0.2.7"
 description = "Volcengine agent development kit, integrations with Volcengine cloud services."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -23,10 +23,11 @@ dependencies = [
     "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.3", # For Volcengine API
-    "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
-    "opensearch-py==2.8.0"    # For OpenSearch database
+    "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 # For OpenSearch database
+    "opensearch-py==2.8.0",
+    "omegaconf>=2.3.0", # For agent builder
 ]
 
 [project.scripts]

veadk_python-0.2.7/tests/test_agent.py

@@ -0,0 +1,207 @@
+# 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.
+
+from unittest.mock import Mock, patch
+
+from google.adk.agents.llm_agent import LlmAgent
+from google.adk.models.lite_llm import LiteLlm
+from google.adk.tools import load_memory
+
+from veadk import Agent
+from veadk.consts import (
+    DEFAULT_AGENT_NAME,
+    DEFAULT_MODEL_AGENT_API_BASE,
+    DEFAULT_MODEL_AGENT_NAME,
+    DEFAULT_MODEL_AGENT_PROVIDER,
+    DEFAULT_MODEL_EXTRA_CONFIG,
+)
+from veadk.knowledgebase import KnowledgeBase
+from veadk.memory.long_term_memory import LongTermMemory
+from veadk.tools import load_knowledgebase_tool
+from veadk.tracing.telemetry.opentelemetry_tracer import OpentelemetryTracer
+
+
+def test_agent():
+    knowledgebase = KnowledgeBase()
+    long_term_memory = LongTermMemory(backend="local")
+    tracer = OpentelemetryTracer()
+
+    extra_config = {
+        "extra_headers": {"thinking": "test"},
+        "extra_body": {"content": "test"},
+    }
+
+    agent = Agent(
+        model_name="test_model_name",
+        model_provider="test_model_provider",
+        model_api_key="test_model_api_key",
+        model_api_base="test_model_api_base",
+        model_extra_config=extra_config,
+        tools=[],
+        sub_agents=[],
+        knowledgebase=knowledgebase,
+        long_term_memory=long_term_memory,
+        tracers=[tracer],
+    )
+
+    assert agent.model.model == f"{agent.model_provider}/{agent.model_name}"  # type: ignore
+
+    expected_config = DEFAULT_MODEL_EXTRA_CONFIG.copy()
+    expected_config["extra_headers"] |= extra_config["extra_headers"]
+    expected_config["extra_body"] |= extra_config["extra_body"]
+
+    assert agent.model_extra_config == expected_config
+
+    assert agent.knowledgebase == knowledgebase
+    assert agent.knowledgebase.backend == "local"  # type: ignore
+    assert load_knowledgebase_tool.knowledgebase == agent.knowledgebase
+    assert load_knowledgebase_tool.load_knowledgebase_tool in agent.tools
+
+    assert agent.long_term_memory.backend == "local"  # type: ignore
+    assert load_memory in agent.tools
+
+
+@patch.dict("os.environ", {"MODEL_AGENT_API_KEY": "mock_api_key"})
+def test_agent_default_values():
+    agent = Agent()
+
+    assert agent.name == DEFAULT_AGENT_NAME
+
+    assert agent.model_name == DEFAULT_MODEL_AGENT_NAME
+    assert agent.model_provider == DEFAULT_MODEL_AGENT_PROVIDER
+    assert agent.model_api_base == DEFAULT_MODEL_AGENT_API_BASE
+
+    assert agent.tools == []
+    assert agent.sub_agents == []
+    assert agent.knowledgebase is None
+    assert agent.long_term_memory is None
+    assert agent.tracers == []
+
+
+@patch.dict("os.environ", {"MODEL_AGENT_API_KEY": "mock_api_key"})
+def test_agent_without_knowledgebase():
+    agent = Agent()
+
+    assert agent.knowledgebase is None
+    assert load_knowledgebase_tool.load_knowledgebase_tool not in agent.tools
+
+
+@patch.dict("os.environ", {"MODEL_AGENT_API_KEY": "mock_api_key"})
+def test_agent_without_long_term_memory():
+    agent = Agent()
+
+    assert agent.long_term_memory is None
+    assert load_memory not in agent.tools
+
+
+@patch("veadk.agent.LiteLlm")
+def test_agent_model_creation(mock_lite_llm):
+    mock_model = Mock()
+    mock_lite_llm.return_value = mock_model
+
+    agent = Agent(
+        model_name="test_model",
+        model_provider="test_provider",
+        model_api_key="test_key",
+        model_api_base="test_base",
+    )
+
+    mock_lite_llm.assert_called_once()
+    assert agent.model == mock_model
+
+
+@patch.dict("os.environ", {"MODEL_AGENT_API_KEY": "mock_api_key"})
+def test_agent_with_existing_model():
+    existing_model = LiteLlm(model="test_model")
+    agent = Agent(model=existing_model)
+
+    assert agent.model == existing_model
+
+
+@patch.dict("os.environ", {"MODEL_AGENT_API_KEY": "mock_api_key"})
+def test_agent_model_extra_config_merge():
+    user_config = {
+        "extra_headers": {"custom": "header"},
+        "extra_body": {"custom": "body"},
+        "other_param": "value",
+    }
+
+    agent = Agent(model_extra_config=user_config)
+
+    expected_headers = DEFAULT_MODEL_EXTRA_CONFIG["extra_headers"].copy()
+    expected_headers["custom"] = "header"
+
+    expected_body = DEFAULT_MODEL_EXTRA_CONFIG["extra_body"].copy()
+    expected_body["custom"] = "body"
+
+    assert agent.model_extra_config["extra_headers"] == expected_headers
+    assert agent.model_extra_config["extra_body"] == expected_body
+    assert agent.model_extra_config["other_param"] == "value"
+
+
+@patch.dict("os.environ", {"MODEL_AGENT_API_KEY": "mock_api_key"})
+def test_agent_empty_model_extra_config():
+    agent = Agent(model_extra_config={})
+
+    assert (
+        agent.model_extra_config["extra_headers"]
+        == DEFAULT_MODEL_EXTRA_CONFIG["extra_headers"]
+    )
+    assert (
+        agent.model_extra_config["extra_body"]
+        == DEFAULT_MODEL_EXTRA_CONFIG["extra_body"]
+    )
+
+
+@patch.dict("os.environ", {"MODEL_AGENT_API_KEY": "mock_api_key"})
+def test_agent_with_tools():
+    mock_tool = Mock()
+    agent = Agent(tools=[mock_tool])
+
+    assert mock_tool in agent.tools
+
+
+@patch.dict("os.environ", {"MODEL_AGENT_API_KEY": "mock_api_key"})
+def test_agent_with_sub_agents():
+    adk_agent = LlmAgent(name="agent")
+    veadk_agent = Agent(name="agent")
+    agent = Agent(sub_agents=[adk_agent, veadk_agent])
+
+    assert adk_agent in agent.sub_agents
+    assert veadk_agent in agent.sub_agents
+    assert adk_agent.parent_agent == agent
+    assert veadk_agent.parent_agent == agent
+
+
+@patch.dict("os.environ", {"MODEL_AGENT_API_KEY": "mock_api_key"})
+def test_agent_with_tracers():
+    tracer1 = OpentelemetryTracer()
+    tracer2 = OpentelemetryTracer()
+
+    agent = Agent(tracers=[tracer1, tracer2])
+
+    assert len(agent.tracers) == 2
+    assert tracer1 in agent.tracers
+    assert tracer2 in agent.tracers
+
+
+@patch.dict("os.environ", {"MODEL_AGENT_API_KEY": "mock_api_key"})
+def test_agent_custom_name_and_description():
+    custom_name = "CustomAgent"
+    custom_description = "A custom agent for testing"
+
+    agent = Agent(name=custom_name, description=custom_description)
+
+    assert agent.name == custom_name
+    assert agent.description == custom_description

{veadk_python-0.2.6 → veadk_python-0.2.7}/tests/test_runner.py

@@ -20,7 +20,13 @@ from veadk.memory.short_term_memory import ShortTermMemory
 from veadk.runner import Runner
 
 
+# Import the standalone function instead of accessing as class method
+from veadk.runner import _convert_messages
+
+
 def _test_convert_messages(runner):
+    """Test message conversion logic using standalone _convert_messages function"""
+    # Test single text message conversion
     message = "test message"
     expected_message = [
         types.Content(
@@ -28,11 +34,16 @@ def _test_convert_messages(runner):
             role="user",
         )
     ]
-    actual_message = runner._convert_messages(
-        message, session_id="test_session_id", upload_inline_data_to_tos=True
+    # Modified: Call _convert_messages directly (not as runner method)
+    actual_message = _convert_messages(
+        message,
+        app_name=runner.app_name,
+        user_id=runner.user_id,
+        session_id="test_session_id",
     )
     assert actual_message == expected_message
 
+    # Test multiple text messages conversion
     message = ["test message 1", "test message 2"]
     expected_message = [
         types.Content(
@@ -44,13 +55,18 @@ def _test_convert_messages(runner):
             role="user",
         ),
     ]
-    actual_message = runner._convert_messages(
-        message, session_id="test_session_id", upload_inline_data_to_tos=True
+    # Modified: Call _convert_messages directly (not as runner method)
+    actual_message = _convert_messages(
+        message,
+        app_name=runner.app_name,
+        user_id=runner.user_id,
+        session_id="test_session_id",
     )
     assert actual_message == expected_message
 
 
 def test_runner():
+    """Test Runner class initialization and core properties"""
     short_term_memory = ShortTermMemory()
     long_term_memory = LongTermMemory(backend="local")
     agent = Agent(
@@ -64,10 +80,9 @@ def test_runner():
     runner = Runner(agent=agent, short_term_memory=short_term_memory)
     assert runner.long_term_memory == agent.long_term_memory
 
-    adk_runner = runner.runner
-    assert adk_runner.memory_service == agent.long_term_memory
-    assert adk_runner.session_service == runner.short_term_memory.session_service
+    # Verify inherited ADKRunner properties
+    assert runner.memory_service == agent.long_term_memory
+    assert runner.session_service == runner.short_term_memory.session_service
 
-    _test_convert_messages(runner)
-    _test_convert_messages(runner)
+    # Run message conversion tests
     _test_convert_messages(runner)

{veadk_python-0.2.6 → veadk_python-0.2.7}/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,11 +26,9 @@ 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_API_BASE,
-    DEFAULT_MODEL_AGENT_NAME,
-    DEFAULT_MODEL_AGENT_PROVIDER,
+    DEFAULT_AGENT_NAME,
     DEFAULT_MODEL_EXTRA_CONFIG,
 )
 from veadk.evaluation import EvalSetRecorder
@@ -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,9 +93,6 @@ 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
 

veadk_python-0.2.7/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_python-0.2.7/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_python-0.2.7/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_python-0.2.7/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