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

veadk/integrations/ve_faas/template/{{cookiecutter.local_dir_name}}/src/app.py

@@ -17,9 +17,17 @@ from contextlib import asynccontextmanager
 from typing import Callable
 
 from agent import agent_run_config
+
 from fastapi import FastAPI
+from fastapi.routing import APIRoute
+
 from fastmcp import FastMCP
 
+from starlette.routing import Route
+
+from google.adk.a2a.utils.agent_card_builder import AgentCardBuilder
+from a2a.types import AgentProvider
+
 from veadk.a2a.ve_a2a_server import init_app
 from veadk.runner import Runner
 from veadk.tracing.telemetry.exporters.apmplus_exporter import APMPlusExporter
@@ -39,6 +47,10 @@ app_name = agent_run_config.app_name
 agent = agent_run_config.agent
 short_term_memory = agent_run_config.short_term_memory
 
+VEFAAS_REGION = os.getenv("APP_REGION", "cn-beijing")
+VEFAAS_FUNC_ID = os.getenv("_FAAS_FUNC_ID", "")
+agent_card_builder = AgentCardBuilder(agent=agent, provider=AgentProvider(organization="Volcengine Agent Development Kit (VeADK)", url=f"https://console.volcengine.com/vefaas/region:vefaas+{VEFAAS_REGION}/function/detail/{VEFAAS_FUNC_ID}"))
+
 
 def load_tracer() -> None:
     EXPORTER_REGISTRY = {
@@ -61,11 +73,8 @@ def load_tracer() -> None:
             else:
                 exporters.append(exporter_cls())
 
-    tracer = OpentelemetryTracer(
-        name="veadk_tracer", app_name=agent_run_config.app_name, exporters=exporters
-    )
+    tracer = OpentelemetryTracer(name="veadk_tracer", exporters=exporters)
     agent_run_config.agent.tracers.extend([tracer])
-    tracer.do_hooks(agent=agent_run_config.agent)
 
 
 def build_mcp_run_agent_func() -> Callable:
@@ -104,8 +113,16 @@ def build_mcp_run_agent_func() -> Callable:
     return run_agent
 
 
+async def agent_card() -> dict:
+    agent_card = await agent_card_builder.build()
+    return agent_card.model_dump()
+
+
 load_tracer()
 
+# Build a run_agent function for building MCP server
+run_agent_func = build_mcp_run_agent_func()
+
 a2a_app = init_app(
     server_url="0.0.0.0",
     app_name=app_name,
@@ -113,9 +130,8 @@ a2a_app = init_app(
     short_term_memory=short_term_memory,
 )
 
-# Build a run_agent function for building MCP server
-run_agent_func = build_mcp_run_agent_func()
 a2a_app.post("/run_agent", operation_id="run_agent", tags=["mcp"])(run_agent_func)
+a2a_app.get("/agent_card", operation_id="agent_card", tags=["mcp"])(agent_card)
 
 
 # === Build mcp server ===
@@ -134,7 +150,14 @@ async def combined_lifespan(app: FastAPI):
 
 
 # Create main FastAPI app with combined lifespan
-app = FastAPI(title=a2a_app.title, version=a2a_app.version, lifespan=combined_lifespan)
+app = FastAPI(
+    title=a2a_app.title,
+    version=a2a_app.version,
+    lifespan=combined_lifespan,
+    openapi_url=None,
+    docs_url=None,
+    redoc_url=None
+)
 
 # Mount A2A routes to main app
 for route in a2a_app.routes:
@@ -143,4 +166,14 @@ for route in a2a_app.routes:
 # Mount MCP server at /mcp endpoint
 app.mount("/mcp", mcp_app)
 
+
+# remove openapi routes
+paths = ["/openapi.json", "/docs", "/redoc"]
+new_routes = []
+for route in app.router.routes:
+    if isinstance(route, (APIRoute, Route)) and route.path in paths:
+        continue
+    new_routes.append(route)
+app.router.routes = new_routes
+
 # === Build mcp server end ===

veadk/integrations/ve_faas/template/{{cookiecutter.local_dir_name}}/src/run.sh

@@ -33,12 +33,18 @@ while [[ $# -gt 0 ]]; do
     esac
 done
 
-# in case of uvicorn and fastapi not installed in user's requirements.txt
-python3 -m pip install uvicorn[standard]
-
-python3 -m pip install fastapi
+# in case of deployment deps not installed in user's requirements.txt
+if pip list | grep -q "^fastapi \|^uvicorn "; then
+    echo "fastapi and uvicorn already installed"
+else
+    python3 -m pip install uvicorn[standard] fastapi
+fi
 
-python3 -m pip install fastmcp
+# Check if MODEL_AGENT_API_KEY is set
+if [ -z "$MODEL_AGENT_API_KEY" ]; then
+    echo "MODEL_AGENT_API_KEY is not set. Please set it in your environment variables."
+    exit 1
+fi
 
 USE_ADK_WEB=${USE_ADK_WEB:-False}
 

veadk/integrations/ve_faas/ve_faas.py

@@ -120,7 +120,11 @@ class VeFaaS:
                 envs=envs,
             )
         )
-        logger.debug(f"Function creation response: {res}")
+
+        # avoid print secrets
+        logger.debug(
+            f"Function creation in {res.project_name} project with ID {res.id}"
+        )
 
         function_id = res.id
 

veadk/integrations/ve_tos/ve_tos.py

@@ -0,0 +1,176 @@
+# 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.config import getenv
+from veadk.utils.logger import get_logger
+import tos
+import asyncio
+from typing import Union
+from pydantic import BaseModel, Field
+from typing import Any
+from urllib.parse import urlparse
+from datetime import datetime
+
+logger = get_logger(__name__)
+
+
+class TOSConfig(BaseModel):
+    region: str = Field(
+        default_factory=lambda: getenv("DATABASE_TOS_REGION"),
+        description="TOS region",
+    )
+    ak: str = Field(
+        default_factory=lambda: getenv("VOLCENGINE_ACCESS_KEY"),
+        description="Volcengine access key",
+    )
+    sk: str = Field(
+        default_factory=lambda: getenv("VOLCENGINE_SECRET_KEY"),
+        description="Volcengine secret key",
+    )
+    bucket_name: str = Field(
+        default_factory=lambda: getenv("DATABASE_TOS_BUCKET"),
+        description="TOS bucket name",
+    )
+
+
+class VeTOS(BaseModel):
+    config: TOSConfig = Field(default_factory=TOSConfig)
+
+    def model_post_init(self, __context: Any) -> None:
+        try:
+            self._client = tos.TosClientV2(
+                self.config.ak,
+                self.config.sk,
+                endpoint=f"tos-{self.config.region}.volces.com",
+                region=self.config.region,
+            )
+            logger.info("Connected to TOS successfully.")
+        except Exception as e:
+            logger.error(f"Client initialization failed:{e}")
+            return None
+
+    def create_bucket(self) -> bool:
+        """If the bucket does not exist, create it"""
+        try:
+            self._client.head_bucket(self.config.bucket_name)
+            logger.info(f"Bucket {self.config.bucket_name} already exists")
+            return True
+        except tos.exceptions.TosServerError as e:
+            if e.status_code == 404:
+                self._client.create_bucket(
+                    bucket=self.config.bucket_name,
+                    storage_class=tos.StorageClassType.Storage_Class_Standard,
+                    acl=tos.ACLType.ACL_Private,
+                )
+                logger.info(f"Bucket {self.config.bucket_name} created successfully")
+                return True
+        except Exception as e:
+            logger.error(f"Bucket creation failed: {str(e)}")
+            return False
+
+    def build_tos_url(
+        self, user_id: str, app_name: str, session_id: str, data_path: str
+    ) -> tuple[str, str]:
+        """generate TOS object key"""
+        parsed_url = urlparse(data_path)
+
+        if parsed_url.scheme and parsed_url.scheme in ("http", "https", "ftp", "ftps"):
+            file_name = os.path.basename(parsed_url.path)
+        else:
+            file_name = os.path.basename(data_path)
+
+        timestamp: str = datetime.now().strftime("%Y%m%d%H%M%S%f")[:-3]
+        object_key: str = f"{app_name}-{user_id}-{session_id}/{timestamp}-{file_name}"
+        tos_url: str = f"https://{self.config.bucket_name}.tos-{self.config.region}.volces.com/{object_key}"
+
+        return object_key, tos_url
+
+    def upload(
+        self,
+        object_key: str,
+        data: Union[str, bytes],
+    ):
+        if isinstance(data, str):
+            data_type = "file"
+        elif isinstance(data, bytes):
+            data_type = "bytes"
+        else:
+            error_msg = f"Upload failed: data type error. Only str (file path) and bytes are supported, got {type(data)}"
+            logger.error(error_msg)
+            raise ValueError(error_msg)
+        if data_type == "file":
+            return asyncio.to_thread(self._do_upload_file, object_key, data)
+        elif data_type == "bytes":
+            return asyncio.to_thread(self._do_upload_bytes, object_key, data)
+
+    def _do_upload_bytes(self, object_key: str, bytes: bytes) -> bool:
+        try:
+            if not self._client:
+                return False
+            if not self.create_bucket():
+                return False
+            self._client.put_object(
+                bucket=self.config.bucket_name, key=object_key, content=bytes
+            )
+            logger.debug(f"Upload success, object_key: {object_key}")
+            self._close()
+            return True
+        except Exception as e:
+            logger.error(f"Upload failed: {e}")
+            self._close()
+            return False
+
+    def _do_upload_file(self, object_key: str, file_path: str) -> bool:
+        try:
+            if not self._client:
+                return False
+            if not self.create_bucket():
+                return False
+
+            self._client.put_object_from_file(
+                bucket=self.config.bucket_name, key=object_key, file_path=file_path
+            )
+            self._close()
+            logger.debug(f"Upload success, object_key: {object_key}")
+            return True
+        except Exception as e:
+            logger.error(f"Upload failed: {e}")
+            self._close()
+            return False
+
+    def download(self, object_key: str, save_path: str) -> bool:
+        """download image from TOS"""
+        try:
+            object_stream = self._client.get_object(self.config.bucket_name, object_key)
+
+            save_dir = os.path.dirname(save_path)
+            if save_dir and not os.path.exists(save_dir):
+                os.makedirs(save_dir, exist_ok=True)
+
+            with open(save_path, "wb") as f:
+                for chunk in object_stream:
+                    f.write(chunk)
+
+            logger.debug(f"Image download success, saved to: {save_path}")
+            return True
+
+        except Exception as e:
+            logger.error(f"Image download failed: {str(e)}")
+
+            return False
+
+    def _close(self):
+        if self._client:
+            self._client.close()

veadk/runner.py

@@ -11,21 +11,28 @@
 # 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 asyncio
 from typing import Union
 
 from google.adk.agents import RunConfig
+from google.adk.agents.invocation_context import LlmCallsLimitExceededError
 from google.adk.agents.run_config import StreamingMode
+from google.adk.plugins.base_plugin import BasePlugin
 from google.adk.runners import Runner as ADKRunner
 from google.genai import types
 from google.genai.types import Blob
 
 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.evaluation import EvalSetRecorder
 from veadk.memory.short_term_memory import ShortTermMemory
 from veadk.types import MediaMessage
 from veadk.utils.logger import get_logger
 from veadk.utils.misc import read_png_to_bytes
+from veadk.integrations.ve_tos.ve_tos import VeTOS
 
 logger = get_logger(__name__)
 
@@ -38,30 +45,36 @@ RunnerMessage = Union[
     list[MediaMessage | str],  # multiple turn prompt with media and text-based prompt
 ]
 
+VeAgent = Union[Agent, RemoteVeAgent, SequentialAgent, ParallelAgent, LoopAgent]
+
 
 class Runner:
     def __init__(
         self,
-        agent: Agent | RemoteVeAgent,
-        short_term_memory: ShortTermMemory,
+        agent: VeAgent,
+        short_term_memory: ShortTermMemory | None = None,
+        plugins: list[BasePlugin] | None = None,
         app_name: str = "veadk_default_app",
         user_id: str = "veadk_default_user",
     ):
-        # basic settings
         self.app_name = app_name
         self.user_id = user_id
 
-        # agent settings
         self.agent = agent
 
-        self.short_term_memory = short_term_memory
-        self.session_service = short_term_memory.session_service
+        if not short_term_memory:
+            logger.info(
+                "No short term memory provided, using a in-memory memory by default."
+            )
+            self.short_term_memory = ShortTermMemory()
+        else:
+            self.short_term_memory = short_term_memory
+
+        self.session_service = self.short_term_memory.session_service
 
         # prevent VeRemoteAgent has no long-term memory attr
         if isinstance(self.agent, Agent):
             self.long_term_memory = self.agent.long_term_memory
-            for tracer in self.agent.tracers:
-                tracer.set_app_name(self.app_name)
         else:
             self.long_term_memory = None
 
@@ -70,15 +83,28 @@ class Runner:
             agent=self.agent,
             session_service=self.session_service,
             memory_service=self.long_term_memory,
+            plugins=plugins,
         )
 
-    def _convert_messages(self, messages) -> list:
+    def _convert_messages(self, messages, session_id) -> list:
         if isinstance(messages, str):
             messages = [types.Content(role="user", parts=[types.Part(text=messages)])]
         elif isinstance(messages, MediaMessage):
             assert messages.media.endswith(".png"), (
                 "The MediaMessage only supports PNG format file for now."
             )
+            data = read_png_to_bytes(messages.media)
+
+            ve_tos = VeTOS()
+            object_key, tos_url = ve_tos.build_tos_url(
+                self.user_id, self.app_name, session_id, messages.media
+            )
+            try:
+                asyncio.create_task(ve_tos.upload(object_key, data))
+            except Exception as e:
+                logger.error(f"Upload to TOS failed: {e}")
+                tos_url = None
+
             messages = [
                 types.Content(
                     role="user",
@@ -86,8 +112,8 @@ class Runner:
                         types.Part(text=messages.text),
                         types.Part(
                             inline_data=Blob(
-                                display_name=messages.media,
-                                data=read_png_to_bytes(messages.media),
+                                display_name=tos_url,
+                                data=data,
                                 mime_type="image/png",
                             )
                         ),
@@ -97,7 +123,7 @@ class Runner:
         elif isinstance(messages, list):
             converted_messages = []
             for message in messages:
-                converted_messages.extend(self._convert_messages(message))
+                converted_messages.extend(self._convert_messages(message, session_id))
             messages = converted_messages
         else:
             raise ValueError(f"Unknown message type: {type(messages)}")
@@ -108,35 +134,44 @@ class Runner:
         self,
         session_id: str,
         message: types.Content,
+        run_config: RunConfig | None = None,
         stream: bool = False,
     ):
         stream_mode = StreamingMode.SSE if stream else StreamingMode.NONE
 
-        async def event_generator():
-            async for event in self.runner.run_async(
-                user_id=self.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
-                    and event.content.parts[0].text is not None
-                    and len(event.content.parts[0].text.strip()) > 0
-                ):
-                    yield event.content.parts[0].text
+        if run_config is not None:
+            stream_mode = run_config.streaming_mode
+        else:
+            run_config = RunConfig(streaming_mode=stream_mode)
+        try:
 
-        final_output = ""
-        async for chunk in event_generator():
+            async def event_generator():
+                async for event in self.runner.run_async(
+                    user_id=self.user_id,
+                    session_id=session_id,
+                    new_message=message,
+                    run_config=run_config,
+                ):
+                    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
+                        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(chunk, end="", flush=True)
-            final_output += chunk
-        if stream:
-            print()  # end with a new line
+                print()  # end with a new line
+        except LlmCallsLimitExceededError as e:
+            logger.warning(f"Max number of llm calls limit exceeded: {e}")
 
         return final_output
 
@@ -145,9 +180,10 @@ class Runner:
         messages: RunnerMessage,
         session_id: str,
         stream: bool = False,
+        run_config: RunConfig | None = None,
         save_tracing_data: bool = False,
     ):
-        converted_messages: list = self._convert_messages(messages)
+        converted_messages: list = self._convert_messages(messages, session_id)
 
         await self.short_term_memory.create_session(
             app_name=self.app_name, user_id=self.user_id, session_id=session_id
@@ -157,19 +193,106 @@ class Runner:
 
         final_output = ""
         for converted_message in converted_messages:
-            final_output = await self._run(session_id, converted_message, stream)
+            final_output = await self._run(
+                session_id, converted_message, run_config, stream
+            )
 
         # try to save tracing file
         if save_tracing_data:
             self.save_tracing_file(session_id)
 
+        self._print_trace_id()
+
         return final_output
 
-    def save_tracing_file(self, session_id: str) -> str:
+    def get_trace_id(self) -> str:
+        if not isinstance(self.agent, Agent):
+            logger.warning(
+                ("The agent is not an instance of VeADK Agent, no trace id provided.")
+            )
+            return "<unknown_trace_id>"
+
+        if not self.agent.tracers:
+            logger.warning(
+                "No tracer is configured in the agent, no trace id provided."
+            )
+            return "<unknown_trace_id>"
+
+        try:
+            trace_id = self.agent.tracers[0].trace_id  # type: ignore
+            return trace_id
+        except Exception as e:
+            logger.warning(f"Get tracer id failed as {e}")
+            return "<unknown_trace_id>"
+
+    async def run_with_raw_message(
+        self,
+        message: types.Content,
+        session_id: str,
+        run_config: RunConfig | None = None,
+    ):
+        run_config = RunConfig() if not run_config else run_config
+
+        await self.short_term_memory.create_session(
+            app_name=self.app_name, user_id=self.user_id, session_id=session_id
+        )
+
+        try:
+
+            async def event_generator():
+                async for event in self.runner.run_async(
+                    user_id=self.user_id,
+                    session_id=session_id,
+                    new_message=message,
+                    run_config=run_config,
+                ):
+                    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
+                        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():
+                final_output += chunk
+        except LlmCallsLimitExceededError as e:
+            logger.warning(f"Max number of llm calls limit exceeded: {e}")
+
+        return final_output
+
+    def _print_trace_id(self) -> None:
         if not isinstance(self.agent, Agent):
+            logger.warning(
+                ("The agent is not an instance of VeADK Agent, no trace id provided.")
+            )
+            return
+
+        if not self.agent.tracers:
+            logger.warning(
+                "No tracer is configured in the agent, no trace id provided."
+            )
+            return
+
+        try:
+            trace_id = self.agent.tracers[0].trace_id  # type: ignore
+            logger.info(f"Trace id: {trace_id}")
+        except Exception as e:
+            logger.warning(f"Get tracer id failed as {e}")
+            return
+
+    def save_tracing_file(self, session_id: str) -> str:
+        if not isinstance(
+            self.agent, (Agent, SequentialAgent, ParallelAgent, LoopAgent)
+        ):
             logger.warning(
                 (
-                    "The agent is not an instance of VeADK Agent, cannot save tracing file."
+                    "The agent is not an instance of Agent, SequentialAgent, ParallelAgent or LoopAgent, cannot save tracing file."
                 )
             )
             return ""