veadk-python 0.5.4__tar.gz → 0.5.6__tar.gz

{veadk_python-0.5.4/veadk_python.egg-info → veadk_python-0.5.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: veadk-python
-Version: 0.5.4
+Version: 0.5.6
 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
@@ -234,8 +234,9 @@ Requires-Dist: pymysql==1.1.1
 Requires-Dist: aiomysql==0.3.2
 Requires-Dist: opensearch-py==2.8.0
 Requires-Dist: filetype==1.2.0
-Requires-Dist: vikingdb-python-sdk==0.1.3
+Requires-Dist: vikingdb-python-sdk>=0.1.3
 Requires-Dist: agentkit-sdk-python>=0.2.0
+Requires-Dist: python-frontmatter==1.1.0
 Provides-Extra: extensions
 Requires-Dist: redis>=5.0; extra == "extensions"
 Requires-Dist: tos>=2.8.4; extra == "extensions"

{veadk_python-0.5.4 → veadk_python-0.5.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "veadk-python"
-version = "0.5.4"
+version = "0.5.6"
 description = "Volcengine agent development kit, integrations with Volcengine cloud services."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -38,8 +38,9 @@ dependencies = [
     "aiomysql==0.3.2", # For async MySQL database (short term memory)
     "opensearch-py==2.8.0",
     "filetype==1.2.0",
-    "vikingdb-python-sdk==0.1.3",
-    "agentkit-sdk-python>=0.2.0"
+    "vikingdb-python-sdk>=0.1.3",
+    "agentkit-sdk-python>=0.2.0",
+    "python-frontmatter==1.1.0",
 ]
 
 [project.scripts]

veadk_python-0.5.6/veadk/a2a/hub/a2a_hub_client.py

@@ -0,0 +1,76 @@
+# 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 requests
+from a2a.types import AgentCard
+
+
+class A2AHubClient:
+    def __init__(self, server_host: str, server_port: int):
+        self.server_host = server_host
+        self.server_port = server_port
+        self.health_check()
+
+    def health_check(self) -> None:
+        """Check the health of the server."""
+        response = requests.get(f"http://{self.server_host}:{self.server_port}/ping")
+        assert response.status_code == 200, (
+            f"unexpected status code from A2A hub server: {response.status_code}"
+        )
+
+    def get_agent_cards(
+        self, group_id: str, target_agents: list[str] = []
+    ) -> list[dict]:
+        """Get the agent cards of the agents in the group."""
+        ret = []
+
+        response = requests.get(
+            f"http://{self.server_host}:{self.server_port}/group/{group_id}/agents"
+        ).json()
+        agent_infos = response["agent_infos"]
+        for agent_info in agent_infos:
+            agent_id = agent_info["agent_id"]
+            if target_agents:
+                if agent_id in target_agents:
+                    ret.append(agent_info)
+            else:
+                ret.append(agent_info)
+
+        return ret
+
+    def register_agent(self, group_id: str, agent_id: str, agent_card: AgentCard):
+        response = requests.post(
+            f"http://{self.server_host}:{self.server_port}/register_agent",
+            json={
+                "group_id": group_id,
+                "agent_id": agent_id,
+                "agent_card": agent_card.model_dump(),
+            },
+        )
+
+        assert response.status_code == 200, (
+            f"unexpected status code from A2A hub server: {response.status_code}"
+        )
+
+    def create_group(self, group_id: str):
+        response = requests.post(
+            f"http://{self.server_host}:{self.server_port}/create_group",
+            params={
+                "group_id": group_id,
+            },
+        )
+
+        assert response.status_code == 200, (
+            f"unexpected status code from A2A hub server: {response.status_code}"
+        )

veadk_python-0.5.6/veadk/a2a/hub/a2a_hub_server.py

@@ -0,0 +1,104 @@
+# 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 uvicorn
+from fastapi import FastAPI
+from fastapi.responses import JSONResponse
+
+from veadk.a2a.hub.models import (
+    AgentInformation,
+    GetAgentResponse,
+    GetAgentsResponse,
+    GetGroupsResponse,
+    RegisterAgentRequest,
+    RegisterAgentResponse,
+    RegisterGroupResponse,
+)
+
+
+class A2AHubServer:
+    def __init__(self):
+        self.app = FastAPI()
+
+        self.groups: list[str] = []
+
+        # group_id -> agent_id -> agent_card
+        self.agent_cards: dict[str, dict[str, dict]] = {}
+
+        @self.app.get("/ping")
+        def ping() -> JSONResponse:
+            return JSONResponse(content={"msg": "pong!"})
+
+        @self.app.post("/create_group")
+        def create_group(group_id: str) -> RegisterGroupResponse:
+            """Create a group."""
+            self.groups.append(group_id)
+            self.agent_cards[group_id] = {}
+            return RegisterGroupResponse(group_id=group_id)
+
+        @self.app.post("/register_agent")
+        def register_agent(
+            request: RegisterAgentRequest,
+        ) -> RegisterAgentResponse:
+            """Register an agent to a specified group."""
+            if request.group_id not in self.groups:
+                return RegisterAgentResponse(
+                    err_code=1, msg=f"group {request.group_id} not exist"
+                )
+            if request.agent_id in self.agent_cards[request.group_id]:
+                return RegisterAgentResponse(
+                    err_code=1, msg=f"agent {request.agent_id} already exist"
+                )
+
+            self.agent_cards[request.group_id][request.agent_id] = request.agent_card
+            return RegisterAgentResponse(
+                group_id=request.group_id,
+                agent_id=request.agent_id,
+                agent_card=self.agent_cards[request.group_id][request.agent_id],
+            )
+
+        @self.app.get("/group/{group_id}/agents")
+        def agents(group_id: str) -> GetAgentsResponse:
+            """Get all agents in a specified group."""
+            if group_id not in self.groups:
+                return GetAgentsResponse(err_code=1, msg=f"group {group_id} not exist")
+
+            agent_infos = [
+                AgentInformation(agent_id=agent_id, agent_card=agent_card)
+                for agent_id, agent_card in self.agent_cards[group_id].items()
+            ]
+            return GetAgentsResponse(group_id=group_id, agent_infos=agent_infos)
+
+        @self.app.get("/group/{group_id}/agent/{agent_id}")
+        def agent(group_id: str, agent_id: str) -> GetAgentResponse:
+            """Get the agent card of a specified agent in a specified group."""
+            if group_id not in self.groups:
+                return GetAgentResponse(err_code=1, msg=f"group {group_id} not exist")
+            if agent_id not in self.agent_cards[group_id]:
+                return GetAgentResponse(
+                    err_code=1,
+                    msg=f"agent {agent_id} in group {group_id} not exist",
+                )
+            return GetAgentResponse(
+                agent_id=agent_id,
+                agent_card=self.agent_cards[group_id][agent_id],
+            )
+
+        @self.app.get("/groups")
+        def groups() -> GetGroupsResponse:
+            """Get all registered groups."""
+            return GetGroupsResponse(group_ids=self.groups)
+
+    def serve(self, **kwargs):
+        uvicorn.run(self.app, **kwargs)

veadk_python-0.5.6/veadk/a2a/hub/models.py

@@ -0,0 +1,78 @@
+# 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 pydantic import BaseModel, Field
+
+
+class BaseResponse(BaseModel):
+    err_code: int = 0
+
+    msg: str = ""
+    """The message of the response."""
+
+
+class RegisterGroupResponse(BaseResponse):
+    group_id: str = ""
+    """The id of the group."""
+
+
+class RegisterAgentRequest(BaseResponse):
+    group_id: str
+    """Target group id."""
+
+    agent_id: str
+    """The id of the agent."""
+
+    agent_card: dict
+    """The agent card of the agent in json format."""
+
+
+class RegisterAgentResponse(BaseResponse):
+    group_id: str = ""
+    """Target group id."""
+
+    agent_id: str = ""
+    """The id of the agent."""
+
+    agent_card: dict = Field(default_factory=dict)
+    """The agent card of the agent in json format."""
+
+
+class AgentInformation(BaseModel):
+    agent_id: str = ""
+    """The id of the agent."""
+
+    agent_card: dict = Field(default_factory=dict)
+    """The agent card of the agent in json format."""
+
+
+class GetAgentsResponse(BaseResponse):
+    group_id: str = ""
+    """Target group id."""
+
+    agent_infos: list[AgentInformation] = Field(default_factory=list)
+    """The agent cards of the agents in json format."""
+
+
+class GetAgentResponse(BaseResponse):
+    agent_id: str = ""
+    """The id of the agent."""
+
+    agent_card: dict = Field(default_factory=dict)
+    """The agent card of the agent in json format."""
+
+
+class GetGroupsResponse(BaseResponse):
+    group_ids: list[str] = Field(default_factory=list)
+    """The ids of the groups."""

{veadk_python-0.5.4 → veadk_python-0.5.6}/veadk/agent.py

@@ -15,7 +15,7 @@
 from __future__ import annotations
 
 import os
-from typing import Optional, Union, AsyncGenerator
+from typing import Dict, Optional, Union
 
 # If user didn't set LITELLM_LOCAL_MODEL_COST_MAP, set it to True
 # to enable local model cost map.
@@ -24,15 +24,14 @@ from typing import Optional, Union, AsyncGenerator
 if not os.getenv("LITELLM_LOCAL_MODEL_COST_MAP"):
     os.environ["LITELLM_LOCAL_MODEL_COST_MAP"] = "True"
 
-from google.adk.agents import LlmAgent, RunConfig, InvocationContext
+import uuid
+
+from google.adk.agents import LlmAgent
 from google.adk.agents.base_agent import BaseAgent
 from google.adk.agents.context_cache_config import ContextCacheConfig
 from google.adk.agents.llm_agent import InstructionProvider, ToolUnion
-from google.adk.agents.run_config import StreamingMode
-from google.adk.events import Event, EventActions
+from google.adk.examples.base_example_provider import BaseExampleProvider
 from google.adk.models.lite_llm import LiteLlm
-from google.adk.runners import Runner
-from google.genai import types
 from pydantic import ConfigDict, Field
 from typing_extensions import Any
 
@@ -41,7 +40,6 @@ from veadk.consts import (
     DEFAULT_AGENT_NAME,
     DEFAULT_MODEL_EXTRA_CONFIG,
 )
-from veadk.evaluation import EvalSetRecorder
 from veadk.knowledgebase import KnowledgeBase
 from veadk.memory.long_term_memory import LongTermMemory
 from veadk.memory.short_term_memory import ShortTermMemory
@@ -54,7 +52,6 @@ from veadk.prompts.prompt_manager import BasePromptManager
 from veadk.tracing.base_tracer import BaseTracer
 from veadk.utils.logger import get_logger
 from veadk.utils.patches import patch_asyncio, patch_tracer
-from veadk.utils.misc import check_litellm_version
 from veadk.version import VERSION
 
 patch_tracer()
@@ -87,10 +84,13 @@ class Agent(LlmAgent):
         tracers (list[BaseTracer]): List of tracers used for telemetry and monitoring.
         enable_authz (bool): Whether to enable agent authorization checks.
         auto_save_session (bool): Whether to automatically save sessions to long-term memory.
+        skills (list[str]): List of skills that equip the agent with specific capabilities.
+        example_store (Optional[BaseExampleProvider]): Example store for providing example Q/A.
     """
 
     model_config = ConfigDict(arbitrary_types_allowed=True, extra="allow")
 
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()).split("-")[0])
     name: str = DEFAULT_AGENT_NAME
     description: str = DEFAULT_DESCRIPTION
     instruction: Union[str, InstructionProvider] = DEFAULT_INSTRUCTION
@@ -144,6 +144,10 @@ class Agent(LlmAgent):
 
     auto_save_session: bool = False
 
+    skills: list[str] = Field(default_factory=list)
+
+    example_store: Optional[BaseExampleProvider] = None
+
     def model_post_init(self, __context: Any) -> None:
         super().model_post_init(None)  # for sub_agents init
 
@@ -171,9 +175,6 @@ class Agent(LlmAgent):
 
         if not self.model:
             if self.enable_responses:
-                min_version = "1.79.3"
-                check_litellm_version(min_version)
-
                 from veadk.models.ark_llm import ArkLlm
 
                 self.model = ArkLlm(
@@ -182,12 +183,6 @@ class Agent(LlmAgent):
                     api_base=self.model_api_base,
                     **self.model_extra_config,
                 )
-                if not self.context_cache_config:
-                    self.context_cache_config = ContextCacheConfig(
-                        cache_intervals=100,  # maximum number
-                        ttl_seconds=315360000,
-                        min_tokens=0,
-                    )
             else:
                 fallbacks = None
                 if isinstance(self.model_name, list):
@@ -285,89 +280,70 @@ class Agent(LlmAgent):
                 else:
                     self.after_agent_callback = save_session_to_long_term_memory
 
+        if self.skills:
+            self.load_skills()
+
+        if self.example_store:
+            from google.adk.tools.example_tool import ExampleTool
+
+            self.tools.append(ExampleTool(examples=self.example_store))
+
         logger.info(f"VeADK version: {VERSION}")
 
         logger.info(f"{self.__class__.__name__} `{self.name}` init done.")
         logger.debug(
-            f"Agent: {self.model_dump(include={'name', 'model_name', 'model_api_base', 'tools'})}"
+            f"Agent: {self.model_dump(include={'id', 'name', 'model_name', 'model_api_base', 'tools', 'skills'})}"
+        )
+
+    def update_model(self, model_name: str):
+        logger.info(f"Updating model to {model_name}")
+        self.model = self.model.model_copy(
+            update={"model": f"{self.model_provider}/{model_name}"}
+        )
+
+    def load_skills(self):
+        from pathlib import Path
+
+        from veadk.skills.skill import Skill
+        from veadk.skills.utils import (
+            load_skills_from_cloud,
+            load_skills_from_directory,
         )
+        from veadk.tools.skills_tools import (
+            SkillsTool,
+            bash_tool,
+            edit_file_tool,
+            read_file_tool,
+            write_file_tool,
+            register_skills_tool,
+        )
+
+        skills: Dict[str, Skill] = {}
 
-    async def _run_async_impl(
-        self, ctx: InvocationContext
-    ) -> AsyncGenerator[Event, None]:
-        if self.enable_responses:
-            if not ctx.context_cache_config:
-                ctx.context_cache_config = self.context_cache_config
-
-        async for event in super()._run_async_impl(ctx):
-            yield event
-            if self.enable_responses and event.cache_metadata:
-                # for persistent short-term memory with response api
-                session_state_event = Event(
-                    invocation_id=event.invocation_id,
-                    author=event.author,
-                    actions=EventActions(
-                        state_delta={
-                            "response_id": event.cache_metadata.cache_name,
-                        }
-                    ),
+        for item in self.skills:
+            if not item or str(item).strip() == "":
+                continue
+            path = Path(item)
+            if path.exists() and path.is_dir():
+                for skill in load_skills_from_directory(path):
+                    skills[skill.name] = skill
+            else:
+                for skill in load_skills_from_cloud(item):
+                    skills[skill.name] = skill
+        if skills:
+            self.instruction += "\nYou have the following skills:\n"
+
+            for skill in skills.values():
+                self.instruction += (
+                    f"- name: {skill.name}\n- description: {skill.description}\n\n"
                 )
-                yield session_state_event
-
-    async def _run(
-        self,
-        runner,
-        user_id: str,
-        session_id: str,
-        message: types.Content,
-        stream: bool,
-        run_processor: Optional[BaseRunProcessor] = None,
-    ):
-        """Internal run method with run processor support.
-
-        Args:
-            runner: The Runner instance.
-            user_id: User ID for the session.
-            session_id: Session ID.
-            message: The message to send.
-            stream: Whether to stream the output.
-            run_processor: Optional run processor to use. If not provided, uses self.run_processor.
-
-        Returns:
-            The final output string.
-        """
-        stream_mode = StreamingMode.SSE if stream else StreamingMode.NONE
-
-        # Use provided run_processor or fall back to instance's run_processor
-        processor = run_processor or self.run_processor
-
-        @processor.process_run(runner=runner, message=message)
-        async def event_generator():
-            async for event in runner.run_async(
-                user_id=user_id,
-                session_id=session_id,
-                new_message=message,
-                run_config=RunConfig(streaming_mode=stream_mode),
-            ):
-                if event.get_function_calls():
-                    for function_call in event.get_function_calls():
-                        logger.debug(f"Function call: {function_call}")
-                elif (
-                    event.content is not None
-                    and event.content.parts[0].text is not None
-                    and len(event.content.parts[0].text.strip()) > 0
-                ):
-                    yield event.content.parts[0].text
-
-        final_output = ""
-        async for chunk in event_generator():
-            if stream:
-                print(chunk, end="", flush=True)
-            final_output += chunk
-        if stream:
-            print()  # end with a new line
-
-        return final_output
+
+            self.tools.append(SkillsTool(skills))
+            self.tools.append(read_file_tool)
+            self.tools.append(write_file_tool)
+            self.tools.append(edit_file_tool)
+            self.tools.append(bash_tool)
+            self.tools.append(register_skills_tool)
 
     def _prepare_tracers(self):
         enable_apmplus_tracer = os.getenv("ENABLE_APMPLUS", "false").lower() == "true"
@@ -415,99 +391,7 @@ class Agent(LlmAgent):
             f"Opentelemetry Tracer init {len(self.tracers[0].exporters)} exporters"  # type: ignore
         )
 
-    async def run(
-        self,
-        prompt: str | list[str],
-        stream: bool = False,
-        app_name: str = "veadk_app",
-        user_id: str = "veadk_user",
-        session_id="veadk_session",
-        load_history_sessions_from_db: bool = False,
-        db_url: str = "",
-        collect_runtime_data: bool = False,
-        eval_set_id: str = "",
-        save_session_to_memory: bool = False,
-        run_processor: Optional[BaseRunProcessor] = None,
-    ):
-        """Running the agent. The runner and session service will be created automatically.
-
-        For production, consider using Google-ADK runner to run agent, rather than invoking this method.
-
-        Args:
-            prompt (str | list[str]): The prompt to run the agent.
-            stream (bool, optional): Whether to stream the output. Defaults to False.
-            app_name (str, optional): The name of the application. Defaults to "veadk_app".
-            user_id (str, optional): The id of the user. Defaults to "veadk_user".
-            session_id (str, optional): The id of the session. Defaults to "veadk_session".
-            load_history_sessions_from_db (bool, optional): Whether to load history sessions from database. Defaults to False.
-            db_url (str, optional): The url of the database. Defaults to "".
-            collect_runtime_data (bool, optional): Whether to collect runtime data. Defaults to False.
-            eval_set_id (str, optional): The id of the eval set. Defaults to "".
-            save_session_to_memory (bool, optional): Whether to save this turn session to memory. Defaults to False.
-            run_processor (Optional[BaseRunProcessor], optional): Optional run processor to use for this run.
-                If not provided, uses the agent's default run_processor. Defaults to None.
-        """
-
-        logger.warning(
-            "Running agent in this function is only for development and testing, do not use this function in production. For production, consider using `Google ADK Runner` to run agent, rather than invoking this method."
+    async def run(self, **kwargs):
+        raise NotImplementedError(
+            "Run method in VeADK agent is deprecated since version 0.5.6. Please use runner.run_async instead. Ref: https://agentkit.gitbook.io/docs/runner/overview"
         )
-        logger.info(
-            f"Run agent {self.name}: app_name: {app_name}, user_id: {user_id}, session_id: {session_id}."
-        )
-        prompt = [prompt] if isinstance(prompt, str) else prompt
-
-        # memory service
-        short_term_memory = ShortTermMemory(
-            backend="database" if load_history_sessions_from_db else "local",
-            db_url=db_url,
-        )
-        session_service = short_term_memory.session_service
-        await short_term_memory.create_session(
-            app_name=app_name, user_id=user_id, session_id=session_id
-        )
-
-        # runner
-        runner = Runner(
-            agent=self,
-            app_name=app_name,
-            session_service=session_service,
-            memory_service=self.long_term_memory,
-        )
-
-        logger.info(f"Begin to process prompt {prompt}")
-        # run
-        final_output = ""
-        for _prompt in prompt:
-            message = types.Content(role="user", parts=[types.Part(text=_prompt)])
-            final_output = await self._run(
-                runner, user_id, session_id, message, stream, run_processor
-            )
-
-        # VeADK features
-        if save_session_to_memory:
-            assert self.long_term_memory is not None, (
-                "Long-term memory is not initialized in agent"
-            )
-            session = await session_service.get_session(
-                app_name=app_name,
-                user_id=user_id,
-                session_id=session_id,
-            )
-            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)
-            dump_path = await eval_set_recorder.dump(app_name, user_id, session_id)
-            self._dump_path = dump_path  # just for test/debug/instrumentation
-
-        if self.tracers:
-            for tracer in self.tracers:
-                tracer.dump(user_id=user_id, session_id=session_id)
-
-        return final_output