veadk-python 0.2.16__tar.gz → 0.2.17__tar.gz

{veadk_python-0.2.16 → veadk_python-0.2.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: veadk-python
-Version: 0.2.16
+Version: 0.2.17
 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

{veadk_python-0.2.16 → veadk_python-0.2.17}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "veadk-python"
-version = "0.2.16"
+version = "0.2.17"
 description = "Volcengine agent development kit, integrations with Volcengine cloud services."
 readme = "README.md"
 requires-python = ">=3.10"

{veadk_python-0.2.16 → veadk_python-0.2.17}/veadk/a2a/remote_ve_agent.py

@@ -34,7 +34,62 @@ def _convert_agent_card_dict_to_obj(agent_card_dict: dict) -> AgentCard:
 
 
 class RemoteVeAgent(RemoteA2aAgent):
-    """Connect to remote agent on VeFaaS platform."""
+    """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. Authentication can be handled either via a bearer token in the HTTP header or via a query string parameter.
+
+    The class extends `RemoteA2aAgent` to provide compatibility with the A2A (Agent-to-Agent) communication layer.
+
+    This constructor connects to a remote VeFaaS agent endpoint, retrieves its metadata (`agent_card`), and sets up an asynchronous HTTP client (`httpx.AsyncClient`) for subsequent communication. Depending on the provided authentication parameters, it supports three connection modes:
+    - **No authentication:** Directly fetches the agent card.
+    - **Header authentication:** Sends a bearer token in the `Authorization` header.
+    - **Query string authentication:** Appends the token to the URL query.
+
+    Attributes:
+        name (str):
+            A unique name identifying this remote agent instance.
+        url (str):
+            The base URL of the remote agent on the VeFaaS platform.
+        auth_token (str | None):
+            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.
+            - `None`: No authentication used.
+
+    Raises:
+        ValueError:
+            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: No authentication
+        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 token in query string
+        agent = RemoteVeAgent(
+            name="query_agent",
+            url="https://vefaas.example.com/agents/query",
+            auth_token="my_secret_token",
+            auth_method="querystring"
+        )
+        ```
+    """
 
     def __init__(
         self,

{veadk_python-0.2.16 → veadk_python-0.2.17}/veadk/agent.py

@@ -47,55 +47,108 @@ logger = get_logger(__name__)
 
 
 class Agent(LlmAgent):
-    """LLM-based Agent with Volcengine capabilities."""
+    """LLM-based Agent with Volcengine capabilities.
+
+    This class represents an intelligent agent powered by LLMs (Large Language Models),
+    integrated with Volcengine's AI framework. It supports memory modules, sub-agents,
+    tracers, knowledge bases, and other advanced features for A2A (Agent-to-Agent)
+    or user-facing scenarios.
+
+    Attributes:
+        name (str): The name of the agent.
+        description (str): A description of the agent, useful in A2A scenarios.
+        instruction (Union[str, InstructionProvider]): The instruction or instruction provider.
+        model_name (str): Name of the model used by the agent.
+        model_provider (str): Provider of the model (e.g., openai).
+        model_api_base (str): The base URL of the model API.
+        model_api_key (str): The API key for accessing the model.
+        model_extra_config (dict): Extra configurations to include in model requests.
+        tools (list[ToolUnion]): Tools available to the agent.
+        sub_agents (list[BaseAgent]): Sub-agents managed by this agent.
+        knowledgebase (Optional[KnowledgeBase]): Knowledge base attached to the agent.
+        short_term_memory (Optional[ShortTermMemory]): Session-based memory for temporary context.
+        long_term_memory (Optional[LongTermMemory]): Cross-session memory for persistent user context.
+        tracers (list[BaseTracer]): List of tracers used for telemetry and monitoring.
+
+    Notes:
+        Before creating your agent, you should get the API Key for your model.
+
+    Examples:
+        ### Simple agent
+
+        Create a simplest agent without any extra settings. All agent attributes are come from environment variables and default values. Like:
+
+        ```python
+        import asyncio
+
+        from veadk import Agent, Runner
+
+        root_agent = Agent()
+
+        runner = Runner(agent=root_agent)
+
+        response = asyncio.run(runner.run("hello"))
+        print(response)
+        ```
+
+        You can set some agent metadata attributes by the following code:
+
+        ```python
+        from veadk import Agent
+
+        from veadk import Agent, Runner
+
+        root_agent = Agent(
+            name="meeting_assistant",
+            description="An assistant that helps user to make meetings.",
+            # system prompt
+            instruction="First learn about user's meeting time, location, and other key informations, and give out a meeting plan.",
+        )
+        ```
+
+        Or, once you want to use your local-serving model or models from other provider, you can specify some model-related configurations in initiation arguments:
+
+        ```python
+        agent = Agent(model_name="", model_api_key="", model_api_base="")
+        ```
+
+        Besides, you can specify some extra options by ARK requirements, such as:
+
+        ```python
+        # disable thinking
+        model_extra_config = {}
+        ```
+
+        In some systems, mulitple-agent based design is necessary, you can implement a multiple-agent system by `sub_agent` argument:
+
+        ```python
+        from veadk import Agent
+        ```
+
+    """
 
     model_config = ConfigDict(arbitrary_types_allowed=True, extra="allow")
-    """The model config"""
 
     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: Union[str, InstructionProvider] = DEFAULT_INSTRUCTION
-    """The instruction for the agent."""
 
     model_name: str = Field(default_factory=lambda: settings.model.name)
-    """The name of the model for agent running."""
-
     model_provider: str = Field(default_factory=lambda: settings.model.provider)
-    """The provider of the model for agent running."""
-
     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: settings.model.api_key)
-    """The api key of the model for agent running."""
-
     model_extra_config: dict = Field(default_factory=dict)
-    """The extra config to include in the model requests."""
 
     tools: list[ToolUnion] = []
-    """The tools provided to agent."""
 
     sub_agents: list[BaseAgent] = Field(default_factory=list, exclude=True)
-    """The sub agents provided to agent."""
 
     knowledgebase: Optional[KnowledgeBase] = None
-    """The knowledgebase provided to agent."""
 
     short_term_memory: Optional[ShortTermMemory] = None
-    """The short term memory provided to agent."""
-
     long_term_memory: Optional[LongTermMemory] = None
-    """The long term memory provided to agent.
-
-    In VeADK, the `long_term_memory` refers to cross-session memory under the same user.
-    """
 
     tracers: list[BaseTracer] = []
-    """The tracers provided to agent."""
 
     def model_post_init(self, __context: Any) -> None:
         super().model_post_init(None)  # for sub_agents init

{veadk_python-0.2.16 → veadk_python-0.2.17}/veadk/agents/loop_agent.py

@@ -29,25 +29,38 @@ logger = get_logger(__name__)
 
 
 class LoopAgent(GoogleADKLoopAgent):
-    """Loop Agent with Volcengine capabilities."""
+    """Loop Agent with several sub agents.
+
+    This agent is capable of looping through and executing all sub-agents sequentially
+    or based on specific conditions. It is designed to operate in environments where
+    multiple agents need to work together in a looped execution flow, such as handling
+    complex, multi-step tasks or workflows. The agent integrates Volcengine’s AI
+    capabilities and supports a variety of tools and tracers for enhanced functionality
+    and performance monitoring.
+
+    Attributes:
+        model_config (ConfigDict): Configuration dictionary for the model.
+        name (str): The name of the agent, default is "veLoopAgent".
+        description (str): A description of the agent, helpful in A2A scenarios.
+        instruction (str): Instructions or principles for function calling and agent execution.
+        sub_agents (list[BaseAgent]): A list of sub-agents managed by the loop agent. Each sub-agent
+            is executed in a looped sequence based on the agent's logic.
+        tracers (list[BaseTracer]): A list of tracers used for monitoring the agent's performance
+            and behavior during execution.
+
+    Examples:
+
+    """
 
     model_config = ConfigDict(arbitrary_types_allowed=True, extra="allow")
-    """The model config"""
 
     name: str = "veLoopAgent"
-    """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."""
 
     sub_agents: list[BaseAgent] = Field(default_factory=list, exclude=True)
-    """The sub agents provided to agent."""
 
     tracers: list[BaseTracer] = []
-    """The tracers provided to agent."""
 
     def model_post_init(self, __context: Any) -> None:
         super().model_post_init(None)  # for sub_agents init

{veadk_python-0.2.16 → veadk_python-0.2.17}/veadk/agents/parallel_agent.py

@@ -29,25 +29,37 @@ logger = get_logger(__name__)
 
 
 class ParallelAgent(GoogleADKParallelAgent):
-    """LLM-based Agent with Volcengine capabilities."""
+    """LLM-based Agent that can execute sub-agents in parallel.
+
+    This agent is capable of executing multiple sub-agents concurrently, making it suitable
+    for scenarios that require parallel execution of multiple tasks or operations. By leveraging
+    parallelism, the agent can handle more complex workflows and improve efficiency by performing
+    independent tasks simultaneously. This design is ideal for scenarios where tasks are independent
+    and can benefit from reduced execution time.
+
+    Attributes:
+        model_config (ConfigDict): Configuration dictionary for the model.
+        name (str): The name of the agent, default is "veParallelAgent".
+        description (str): A description of the agent, useful in A2A scenarios.
+        instruction (str): Instructions or principles for function calling and agent execution.
+        sub_agents (list[BaseAgent]): A list of sub-agents managed by the parallel agent.
+            Each sub-agent is executed concurrently.
+        tracers (list[BaseTracer]): A list of tracers used for monitoring the agent's performance
+            and behavior during parallel execution.
+
+    Examples:
+
+    """
 
     model_config = ConfigDict(arbitrary_types_allowed=True, extra="allow")
-    """The model config"""
 
     name: str = "veParallelAgent"
-    """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."""
 
     sub_agents: list[BaseAgent] = Field(default_factory=list, exclude=True)
-    """The sub agents provided to agent."""
 
     tracers: list[BaseTracer] = []
-    """The tracers provided to agent."""
 
     def model_post_init(self, __context: Any) -> None:
         super().model_post_init(None)  # for sub_agents init

{veadk_python-0.2.16 → veadk_python-0.2.17}/veadk/agents/sequential_agent.py

@@ -29,25 +29,34 @@ logger = get_logger(__name__)
 
 
 class SequentialAgent(GoogleADKSequentialAgent):
-    """Sequential Agent with Volcengine capabilities."""
+    """Sequential Agent that executes sub-agents sequentially.
+
+    This agent is designed to execute multiple sub-agents in a predefined sequential order.
+    It ensures that each sub-agent is executed one after the other, making it suitable for
+    workflows where the output of one sub-agent is needed as input for the next. The agent
+    is well-suited for tasks that require a linear progression of steps or operations, ensuring
+    that the execution flow is maintained.
+
+    Attributes:
+        model_config (ConfigDict): Configuration dictionary for the model.
+        name (str): The name of the agent, default is "veSequentialAgent".
+        description (str): A description of the agent, useful in A2A scenarios.
+        instruction (str): Instructions or principles for function calling and agent execution.
+        sub_agents (list[BaseAgent]): A list of sub-agents managed by the sequential agent.
+            Each sub-agent is executed in the order they are listed.
+        tracers (list[BaseTracer]): A list of tracers used for monitoring the agent's performance
+            and behavior during sequential execution.
+    """
 
     model_config = ConfigDict(arbitrary_types_allowed=True, extra="allow")
-    """The model config"""
 
     name: str = "veSequentialAgent"
-    """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."""
 
     sub_agents: list[BaseAgent] = Field(default_factory=list, exclude=True)
-    """The sub agents provided to agent."""
 
     tracers: list[BaseTracer] = []
-    """The tracers provided to agent."""
 
     def model_post_init(self, __context: Any) -> None:
         super().model_post_init(None)  # for sub_agents init

veadk_python-0.2.17/veadk/auth/veauth/apmplus_veauth.py

@@ -0,0 +1,58 @@
+# 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 veadk.auth.veauth.utils import get_credential_from_vefaas_iam
+from veadk.utils.logger import get_logger
+from veadk.utils.volcengine_sign import ve_request
+
+logger = get_logger(__name__)
+
+
+def get_apmplus_token(region: str = "cn-beijing") -> str:
+    logger.info("Fetching APMPlus token...")
+
+    access_key = os.getenv("VOLCENGINE_ACCESS_KEY")
+    secret_key = os.getenv("VOLCENGINE_SECRET_KEY")
+    session_token = ""
+
+    if not (access_key and secret_key):
+        # try to get from vefaas iam
+        cred = get_credential_from_vefaas_iam()
+        access_key = cred.access_key_id
+        secret_key = cred.secret_access_key
+        session_token = cred.session_token
+
+    res = ve_request(
+        request_body={},
+        header={
+            "X-Security-Token": session_token,
+            # APMPlus frontend required
+            "X-Apmplus-Region": region.replace("-", "_"),
+        },
+        action="GetAppKey",
+        ak=access_key,
+        sk=secret_key,
+        service="apmplus_server",
+        version="2024-07-30",
+        region=region,
+        host="open.volcengineapi.com",
+    )
+    try:
+        api_key = res["data"]["app_key"]
+        logger.info("Successfully fetching APMPlus API Key.")
+        return api_key
+    except KeyError:
+        raise ValueError(f"Failed to get APMPlus token: {res}")

{veadk_python-0.2.16 → veadk_python-0.2.17}/veadk/auth/veauth/ark_veauth.py

@@ -64,6 +64,8 @@ def get_ark_token(region: str = "cn-beijing") -> str:
         host="open.volcengineapi.com",
     )
     try:
-        return res["Result"]["ApiKey"]
+        api_key = res["Result"]["ApiKey"]
+        logger.info("Successfully fetching ARK API Key.")
+        return api_key
     except KeyError:
         raise ValueError(f"Failed to get ARK api key: {res}")

{veadk_python-0.2.16 → veadk_python-0.2.17}/veadk/auth/veauth/utils.py

@@ -50,8 +50,20 @@ def get_credential_from_vefaas_iam() -> VeIAMCredential:
         access_key = cred_dict["access_key_id"]
         secret_key = cred_dict["secret_access_key"]
         session_token = cred_dict["session_token"]
+
+        logger.info("Get credential from IAM file successfully.")
+
         return VeIAMCredential(
             access_key_id=access_key,
             secret_access_key=secret_key,
             session_token=session_token,
         )
+
+
+def refresh_ak_sk(access_key: str, secret_key: str) -> VeIAMCredential:
+    if access_key and secret_key:
+        return VeIAMCredential(
+            access_key_id=access_key, secret_access_key=secret_key, session_token=""
+        )
+
+    return get_credential_from_vefaas_iam()

veadk_python-0.2.17/veadk/auth/veauth/viking_mem0_veauth.py

@@ -0,0 +1,91 @@
+# 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 veadk.auth.veauth.utils import get_credential_from_vefaas_iam
+from veadk.utils.logger import get_logger
+from veadk.utils.volcengine_sign import ve_request
+
+logger = get_logger(__name__)
+
+
+def _get_api_key_id_by_project_id(
+    project_id: str, access_key: str, secret_key: str, session_token: str, region: str
+):
+    res = ve_request(
+        request_body={"MemoryProjectId": project_id},
+        header={"X-Security-Token": session_token},
+        action="DescribeMemoryProjectDetail",
+        ak=access_key,
+        sk=secret_key,
+        service="mem0",
+        version="2025-10-10",
+        region=region,
+        host="open.volcengineapi.com",
+    )
+    try:
+        api_key_id = res["Result"]["APIKeyInfos"]["APIKeyId"]
+    except KeyError:
+        raise ValueError(f"Failed to get mem0 api key id: {res}")
+
+    return api_key_id
+
+
+def _get_api_key_by_api_key_id(
+    api_key_id: str, access_key: str, secret_key: str, session_token: str, region: str
+) -> str:
+    res = ve_request(
+        request_body={"APIKeyId": api_key_id},
+        header={"X-Security-Token": session_token},
+        action="DescribeAPIKeyDetail",
+        ak=access_key,
+        sk=secret_key,
+        service="mem0",
+        version="2025-10-10",
+        region=region,
+        host="open.volcengineapi.com",
+    )
+    try:
+        api_key = res["Result"]["APIKeyValue"]
+    except KeyError:
+        raise ValueError(f"Failed to get mem0 api key: {res}")
+
+    return api_key
+
+
+def get_viking_mem0_token(
+    api_key_id: str, memory_project_id: str, region: str = "cn-beijing"
+) -> str:
+    logger.info("Fetching Viking mem0 token...")
+
+    access_key = os.getenv("VOLCENGINE_ACCESS_KEY")
+    secret_key = os.getenv("VOLCENGINE_SECRET_KEY")
+    session_token = ""
+
+    if not (access_key and secret_key):
+        # try to get from vefaas iam
+        cred = get_credential_from_vefaas_iam()
+        access_key = cred.access_key_id
+        secret_key = cred.secret_access_key
+        session_token = cred.session_token
+
+    if not api_key_id:
+        api_key_id = _get_api_key_id_by_project_id(
+            memory_project_id, access_key, secret_key, session_token, region
+        )
+
+    return _get_api_key_by_api_key_id(
+        api_key_id, access_key, secret_key, session_token, region
+    )

{veadk_python-0.2.16 → veadk_python-0.2.17}/veadk/cli/cli.py

@@ -32,7 +32,11 @@ from veadk.version import VERSION
     version=VERSION, prog_name="Volcengine Agent Development Kit (VeADK)"
 )
 def veadk():
-    """Volcengine ADK command line tools"""
+    """Volcengine Agent Development Kit (VeADK) command line interface.
+
+    This is the main entry point for all VeADK CLI commands. VeADK provides
+    tools for developing, deploying, and managing AI agents on the Volcengine platform.
+    """
     pass
 
 

{veadk_python-0.2.16 → veadk_python-0.2.17}/veadk/cli/cli_create.py

@@ -46,6 +46,16 @@ You can run the agent by executing: veadk web
 
 
 def _prompt_for_ark_api_key() -> str:
+    """Prompt user to enter ARK API key with guidance and options.
+
+    Displays instructions for obtaining an ARK API key and provides the user
+    with two options: enter the key immediately or configure it later in the
+    generated .env file. Includes helpful documentation links and clear choices.
+
+    Returns:
+        str: The ARK API key entered by the user, or empty string if they
+            choose to configure it later
+    """
     click.secho(
         "An API key is required to run the agent. See https://www.volcengine.com/docs/82379/1541594 for details.",
         fg="green",
@@ -62,6 +72,30 @@ def _prompt_for_ark_api_key() -> str:
 
 
 def _generate_files(ark_api_key: str, target_dir_path: Path) -> None:
+    """Generate agent project files from templates in the target directory.
+
+    Creates the essential files for a new VeADK agent project including
+    environment configuration, Python package initialization, and the main
+    agent definition file. Uses predefined templates to ensure consistent
+    project structure and proper configuration.
+
+    Args:
+        ark_api_key: ARK API key to be written to the .env file for
+            model authentication. Can be empty string if not provided
+        target_dir_path: Path object pointing to the target directory
+            where files should be created
+
+    Files Created:
+        - .env: Environment file with ARK API key configuration
+        - __init__.py: Python package initialization file
+        - agent.py: Main agent definition with default configuration
+
+    Note:
+        - Creates target directory if it doesn't exist
+        - Overwrites existing files without warning
+        - Uses template formatting to inject API key into .env file
+        - Displays success message with project location after completion
+    """
     target_dir_path.mkdir(exist_ok=True)
     env_path = target_dir_path / ".env"
     init_file_path = target_dir_path / "__init__.py"
@@ -82,7 +116,34 @@ def _generate_files(ark_api_key: str, target_dir_path: Path) -> None:
 @click.argument("agent_name", required=False)
 @click.option("--ark-api-key", help="The ARK API key.")
 def create(agent_name: str, ark_api_key: str) -> None:
-    """Creates a new agent in the current folder with prepopulated agent template."""
+    """Create a new VeADK agent project with prepopulated template files.
+
+    This command creates a new agent project directory with all necessary
+    files to get started with VeADK agent development. It sets up a complete
+    project structure including environment configuration, agent definition,
+    and package initialization.
+
+    The command handles interactive prompts for missing parameters and provides
+    safety checks for existing directories to prevent accidental overwrites.
+
+    Project Structure Created:
+        agent_name/
+        ├── .env                 # Environment configuration with API key
+        ├── __init__.py         # Python package initialization
+        └── agent.py            # Main agent definition with default settings
+
+    Args:
+        agent_name: Name of the agent and directory to create. If not provided
+            as an argument, the user will be prompted to enter it interactively
+        ark_api_key: ARK API key for model authentication. If not provided,
+            the user will be prompted with options to enter it or configure later
+
+    Note:
+        - Agent name becomes both the directory name and project identifier
+        - API key can be configured later by editing the .env file
+        - Generated agent is immediately runnable with 'veadk web' command
+        - Template includes comments guiding users to customize model settings
+    """
     if not agent_name:
         agent_name = click.prompt("Enter the agent name")
     if not ark_api_key: