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

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

@@ -17,9 +17,16 @@ 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 veadk.a2a.ve_a2a_server import init_app
 from veadk.runner import Runner
 from veadk.tracing.telemetry.exporters.apmplus_exporter import APMPlusExporter
@@ -39,6 +46,8 @@ app_name = agent_run_config.app_name
 agent = agent_run_config.agent
 short_term_memory = agent_run_config.short_term_memory
 
+agent_card_builder = AgentCardBuilder(agent=agent)
+
 
 def load_tracer() -> None:
     EXPORTER_REGISTRY = {
@@ -61,11 +70,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 +110,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 +127,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 +147,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 +163,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,8 @@ 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
-
-python3 -m pip install fastmcp
+# in case of deployment deps not installed in user's requirements.txt
+python3 -m pip install uvicorn[standard] fastapi
 
 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/runner.py

@@ -15,12 +15,16 @@ from typing import Union
 
 from google.adk.agents import RunConfig
 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
@@ -38,12 +42,15 @@ 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,
+        agent: VeAgent,
         short_term_memory: ShortTermMemory,
+        plugins: list[BasePlugin] | None = None,
         app_name: str = "veadk_default_app",
         user_id: str = "veadk_default_user",
     ):
@@ -60,8 +67,6 @@ class Runner:
         # 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,6 +75,7 @@ class Runner:
             agent=self.agent,
             session_service=self.session_service,
             memory_service=self.long_term_memory,
+            plugins=plugins,
         )
 
     def _convert_messages(self, messages) -> list:
@@ -163,13 +169,57 @@ class Runner:
         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>"
+
+    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 ""

veadk/tracing/base_tracer.py

@@ -12,214 +12,39 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import json
 from abc import ABC, abstractmethod
-from typing import Any, Optional
-
-from google.adk.agents.callback_context import CallbackContext
-from google.adk.models.llm_request import LlmRequest
-from google.adk.models.llm_response import LlmResponse
-from google.adk.tools import BaseTool, ToolContext
-from opentelemetry import trace
 
 from veadk.utils.logger import get_logger
 
 logger = get_logger(__name__)
 
 
+def replace_bytes_with_empty(data):
+    """
+    Recursively traverse the data structure and replace all bytes types with empty strings.
+    Supports handling any nested structure of lists and dictionaries.
+    """
+    if isinstance(data, dict):
+        # Handle dictionary: Recursively process each value
+        return {k: replace_bytes_with_empty(v) for k, v in data.items()}
+    elif isinstance(data, list):
+        # Handle list: Recursively process each element
+        return [replace_bytes_with_empty(item) for item in data]
+    elif isinstance(data, bytes):
+        # When encountering the bytes type, replace it with an empty string
+        return "<image data>"
+    else:
+        # Keep other types unchanged
+        return data
+
+
 class BaseTracer(ABC):
     def __init__(self, name: str):
-        self.app_name = "veadk_app_name"
-        pass
+        self.name = name
+        self._trace_id = "<unknown_trace_id>"
+        self._trace_file_path = "<unknown_trace_file_path>"
 
     @abstractmethod
-    def dump(self, user_id: str, session_id: str, path: str = "/tmp") -> str: ...
-
-    def tracer_hook_before_model(
-        self, callback_context: CallbackContext, llm_request: LlmRequest
-    ) -> Optional[LlmResponse]:
-        """agent run stage"""
-        trace.get_tracer("gcp.vertex.agent")
-        span = trace.get_current_span()
-        # logger.debug(f"llm_request: {llm_request}")
-
-        req = llm_request.model_dump()
-
-        app_name = getattr(self, "app_name", "veadk_app")
-        agent_name = callback_context.agent_name
-        model_name = req.get("model", "unknown")
-        max_tokens = (
-            None
-            if not req.get("live_connect_config")
-            else req["live_connect_config"].get("max_output_tokens", None)
-        )
-        temperature = (
-            None
-            if not req.get("live_connect_config")
-            else req["live_connect_config"].get("temperature", None)
-        )
-        top_p = (
-            None
-            if not req.get("live_connect_config")
-            else req["live_connect_config"].get("top_p", None)
-        )
-
-        attributes = {}
-        attributes["agent.name"] = agent_name
-        attributes["app.name"] = app_name
-        attributes["gen_ai.system"] = "veadk"
-        if model_name:
-            attributes["gen_ai.request.model"] = model_name
-            attributes["gen_ai.response.model"] = (
-                model_name  # The req model and the resp model should be consistent.
-            )
-        attributes["gen_ai.request.type"] = "completion"
-        if max_tokens:
-            attributes["gen_ai.request.max_tokens"] = max_tokens
-        if temperature:
-            attributes["gen_ai.request.temperature"] = temperature
-        if top_p:
-            attributes["gen_ai.request.top_p"] = top_p
-
-        # Print attributes for debugging
-        # print("Tracing attributes:", attributes)
-
-        # Set all attributes at once if possible, else fallback to individual
-        if hasattr(span, "set_attributes"):
-            span.set_attributes(attributes)
-        else:
-            # Fallback for OpenTelemetry versions without set_attributes
-            for k, v in attributes.items():
-                span.set_attribute(k, v)
-
-    def tracer_hook_after_model(
-        self, callback_context: CallbackContext, llm_response: LlmResponse
-    ) -> Optional[LlmResponse]:
-        """call llm stage"""
-        trace.get_tracer("gcp.vertex.agent")
-        span = trace.get_current_span()
-        # logger.debug(f"llm_response: {llm_response}")
-        # logger.debug(f"callback_context: {callback_context}")
-
-        # Refined: collect all attributes, use set_attributes, print for debugging
-        attributes = {}
-
-        app_name = getattr(self, "app_name", "veadk_app")
-        agent_name = callback_context.agent_name
-        attributes["agent.name"] = agent_name
-        attributes["app.name"] = app_name
-
-        # prompt
-        user_content = callback_context.user_content
-        role = None
-        content = None
-        if getattr(user_content, "role", None):
-            role = getattr(user_content, "role", None)
-
-        if user_content and getattr(user_content, "parts", None):
-            content = user_content.model_dump(exclude_none=True).get("parts", None)
-            content = json.dumps(content) if content else None
-
-        if role and content:
-            attributes["gen_ai.prompt.0.role"] = role
-            attributes["gen_ai.prompt.0.content"] = content
-
-        # completion
-        completion_content = getattr(llm_response, "content").model_dump(
-            exclude_none=True
-        )
-        if completion_content:
-            content = json.dumps(
-                getattr(llm_response, "content").model_dump(exclude_none=True)["parts"]
-            )
-            role = getattr(llm_response, "content").model_dump(exclude_none=True)[
-                "role"
-            ]
-            if role and content:
-                attributes["gen_ai.completion.0.role"] = role
-                attributes["gen_ai.completion.0.content"] = content
-
-        if not llm_response.usage_metadata:
-            return
-
-        # tokens
-        metadata = llm_response.usage_metadata.model_dump()
-        if metadata:
-            prompt_tokens = metadata.get("prompt_token_count", None)
-            completion_tokens = metadata.get("candidates_token_count", None)
-            total_tokens = metadata.get("total_token_count", None)
-            cache_read_input_tokens = (
-                metadata.get("cache_read_input_tokens") or 0
-            )  # Might change, once openai introduces their equivalent.
-            cache_create_input_tokens = (
-                metadata.get("cache_create_input_tokens") or 0
-            )  # Might change, once openai introduces their equivalent.
-            if prompt_tokens:
-                attributes["gen_ai.usage.prompt_tokens"] = prompt_tokens
-            if completion_tokens:
-                attributes["gen_ai.usage.completion_tokens"] = completion_tokens
-            if total_tokens:
-                attributes["gen_ai.usage.total_tokens"] = total_tokens
-            if cache_read_input_tokens is not None:
-                attributes["gen_ai.usage.cache_read_input_tokens"] = (
-                    cache_read_input_tokens
-                )
-            if cache_create_input_tokens is not None:
-                attributes["gen_ai.usage.cache_create_input_tokens"] = (
-                    cache_create_input_tokens
-                )
-
-        # Print attributes for debugging
-        # print("Tracing attributes:", attributes)
-
-        # Set all attributes at once if possible, else fallback to individual
-        if hasattr(span, "set_attributes"):
-            span.set_attributes(attributes)
-        else:
-            # Fallback for OpenTelemetry versions without set_attributes
-            for k, v in attributes.items():
-                span.set_attribute(k, v)
-
-    def tracer_hook_after_tool(
-        self,
-        tool: BaseTool,
-        args: dict[str, Any],
-        tool_context: ToolContext,
-        tool_response: dict,
-    ):
-        trace.get_tracer("gcp.vertex.agent")
-        span = trace.get_current_span()
-        agent_name = tool_context.agent_name
-        tool_name = tool.name
-        app_name = getattr(self, "app_name", "veadk_app")
-        attributes = {
-            "agent.name": agent_name,
-            "app.name": app_name,
-            "tool.name": tool_name,
-        }
-
-        # Set all attributes at once if possible, else fallback to individual
-        if hasattr(span, "set_attributes"):
-            span.set_attributes(attributes)
-        else:
-            # Fallback for OpenTelemetry versions without set_attributes
-            for k, v in attributes.items():
-                span.set_attribute(k, v)
-
-    def set_app_name(self, app_name):
-        self.app_name = app_name
-
-    def do_hooks(self, agent) -> None:
-        if not getattr(agent, "before_model_callback", None):
-            agent.before_model_callback = []
-        if not getattr(agent, "after_model_callback", None):
-            agent.after_model_callback = []
-        if not getattr(agent, "after_tool_callback", None):
-            agent.after_tool_callback = []
-
-        if self.tracer_hook_before_model not in agent.before_model_callback:
-            agent.before_model_callback.append(self.tracer_hook_before_model)
-        if self.tracer_hook_after_model not in agent.after_model_callback:
-            agent.after_model_callback.append(self.tracer_hook_after_model)
-        if self.tracer_hook_after_tool not in agent.after_tool_callback:
-            agent.after_tool_callback.append(self.tracer_hook_after_tool)
+    def dump(self, user_id: str, session_id: str, path: str = "/tmp") -> str:
+        """Dump the trace data to a local file."""
+        ...

veadk/tracing/telemetry/{metrics/__init__.py → attributes/attributes.py}

@@ -11,3 +11,19 @@
 # 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 veadk.tracing.telemetry.attributes.extractors.common_attributes_extractors import (
+    COMMON_ATTRIBUTES,
+)
+from veadk.tracing.telemetry.attributes.extractors.llm_attributes_extractors import (
+    LLM_ATTRIBUTES,
+)
+from veadk.tracing.telemetry.attributes.extractors.tool_attributes_extractors import (
+    TOOL_ATTRIBUTES,
+)
+
+ATTRIBUTES = {
+    "common": COMMON_ATTRIBUTES,
+    "llm": LLM_ATTRIBUTES,
+    "tool": TOOL_ATTRIBUTES,
+}

veadk/tracing/telemetry/attributes/extractors/common_attributes_extractors.py

@@ -0,0 +1,71 @@
+# 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 veadk.version import VERSION
+
+
+def common_gen_ai_system(**kwargs) -> str:
+    """This field will be parsed as `model_provider` in Volcengine CozeLoop platform."""
+    model_provider = kwargs.get("model_provider")
+    return model_provider or "<unknown_model_provider>"
+
+
+def common_gen_ai_system_version(**kwargs) -> str:
+    return VERSION
+
+
+def common_gen_ai_app_name(**kwargs) -> str:
+    app_name = kwargs.get("app_name")
+    return app_name or "<unknown_app_name>"
+
+
+def common_gen_ai_agent_name(**kwargs) -> str:
+    agent_name = kwargs.get("agent_name")
+    return agent_name or "<unknown_agent_name>"
+
+
+def common_gen_ai_user_id(**kwargs) -> str:
+    user_id = kwargs.get("user_id")
+    return user_id or "<unknown_user_id>"
+
+
+def common_gen_ai_session_id(**kwargs) -> str:
+    session_id = kwargs.get("session_id")
+    return session_id or "<unknown_session_id>"
+
+
+def common_cozeloop_report_source(**kwargs) -> str:
+    return "veadk"
+
+
+def llm_openinference_instrumentation_veadk(**kwargs) -> str:
+    return VERSION
+
+
+COMMON_ATTRIBUTES = {
+    "gen_ai.system": common_gen_ai_system,
+    "gen_ai.system.version": common_gen_ai_system_version,
+    "gen_ai.agent.name": common_gen_ai_agent_name,
+    "openinference.instrumentation.veadk": llm_openinference_instrumentation_veadk,
+    "gen_ai.app.name": common_gen_ai_app_name,  # APMPlus required
+    "gen_ai.user.id": common_gen_ai_user_id,  # APMPlus required
+    "gen_ai.session.id": common_gen_ai_session_id,  # APMPlus required
+    "agent_name": common_gen_ai_agent_name,  # CozeLoop required
+    "agent.name": common_gen_ai_agent_name,  # TLS required
+    "app_name": common_gen_ai_app_name,  # CozeLoop required
+    "app.name": common_gen_ai_app_name,  # TLS required
+    "user.id": common_gen_ai_user_id,  # CozeLoop / TLS required
+    "session.id": common_gen_ai_session_id,  # CozeLoop / TLS required
+    "cozeloop.report.source": common_cozeloop_report_source,  # CozeLoop required
+}