agentkit-sdk-python 0.1.15__tar.gz → 0.2.1__tar.gz

{agentkit_sdk_python-0.1.15/agentkit_sdk_python.egg-info → agentkit_sdk_python-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentkit-sdk-python
-Version: 0.1.15
+Version: 0.2.1
 Summary: Python SDK for transforming any AI agent into a production-ready application. Framework-agnostic primitives for runtime, memory, authentication, and tools with volcengine-managed infrastructure.
 Author-email: Xiangrui Cheng <innsdcc@gmail.com>, Yumeng Bao <baoyumeng.123@gmail.com>, Yaozheng Fang <fangyozheng@gmail.com>, Guodong Li <cu.eric.lee@gmail.com>
 License:                                  Apache License
@@ -220,14 +220,15 @@ License-File: LICENSE
 Requires-Dist: a2a-sdk>=0.3.7
 Requires-Dist: fastapi>=0.117.1
 Requires-Dist: fastmcp>=2.12.3
-Requires-Dist: opentelemetry-api>=1.32.1
-Requires-Dist: opentelemetry-exporter-otlp-proto-common>=1.32.1
-Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.32.1
-Requires-Dist: opentelemetry-sdk>=1.32.1
+Requires-Dist: opentelemetry-api<=1.37.0,>=1.32.1
+Requires-Dist: opentelemetry-exporter-otlp-proto-common<=1.37.0,>=1.32.1
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<=1.37.0,>=1.32.1
+Requires-Dist: opentelemetry-sdk<=1.37.0,>=1.32.1
 Requires-Dist: pydantic>=2.11.9
 Requires-Dist: requests>=2.32.5
 Requires-Dist: uvicorn>=0.37.0
 Requires-Dist: pyyaml
+Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: prompt_toolkit
 Requires-Dist: typer
 Requires-Dist: rich
@@ -236,7 +237,7 @@ Requires-Dist: jinja2
 Requires-Dist: tos>=2.8.7
 Requires-Dist: volcengine
 Requires-Dist: pyfiglet>=1.0.2
-Requires-Dist: urllib3<2.6.0
+Requires-Dist: pyreadline3; sys_platform == "win32"
 Provides-Extra: extensions
 Provides-Extra: toolkit
 Provides-Extra: dev

{agentkit_sdk_python-0.1.15 → agentkit_sdk_python-0.2.1}/agentkit/apps/a2a_app/a2a_app.py

@@ -13,9 +13,11 @@
 # limitations under the License.
 
 import logging
-from typing import Callable, override
-
+import os
 import uvicorn
+import inspect
+
+from typing import Callable, override
 from a2a.server.agent_execution import AgentExecutor
 from a2a.server.agent_execution.context import RequestContext
 from a2a.server.apps import A2AStarletteApplication
@@ -24,9 +26,13 @@ from a2a.server.request_handlers import DefaultRequestHandler
 from a2a.server.tasks import InMemoryTaskStore
 from a2a.server.tasks.task_store import TaskStore
 from a2a.types import AgentCard
+from starlette.applications import Starlette
+from starlette.responses import JSONResponse, Response
+from starlette.routing import Route
+from starlette.requests import Request
 
-from agentkit.apps.base_app import BaseAgentkitApp
 from agentkit.apps.a2a_app.telemetry import telemetry
+from agentkit.apps.base_app import BaseAgentkitApp
 
 logger = logging.getLogger(__name__)
 
@@ -69,6 +75,7 @@ class AgentkitA2aApp(BaseAgentkitApp):
 
         self._agent_executor: AgentExecutor | None = None
         self._task_store: TaskStore | None = None
+        self._ping_func: Callable | None = None
 
     def agent_executor(self, **kwargs) -> Callable:
         """Wrap an AgentExecutor class, init it, then bind it to the app instance."""
@@ -111,6 +118,70 @@ class AgentkitA2aApp(BaseAgentkitApp):
 
         return wrapper
 
+    def ping(self, func: Callable) -> Callable:
+        """Register a zero-argument health check function and expose it via GET /ping.
+
+        The function must accept no arguments and should return either a string or a dict.
+        The response shape mirrors SimpleApp: {"status": <str|dict>}.
+        """
+        # Ensure zero-argument function similar to SimpleApp
+        if len(list(inspect.signature(func).parameters.keys())) != 0:
+            raise AssertionError(
+                f"Health check function `{func.__name__}` should not receive any arguments."
+            )
+
+        self._ping_func = func
+        return func
+
+    def _format_ping_status(self, result: str | dict) -> dict:
+        # Align behavior with SimpleApp: always wrap into {"status": result}
+        if isinstance(result, (str, dict)):
+            return {"status": result}
+        logger.error(
+            f"Health check function {getattr(self._ping_func, '__name__', 'unknown')} must return `dict` or `str` type."
+        )
+        return {"status": "error", "message": "Invalid response type."}
+
+    async def ping_endpoint(self, request: Request) -> Response:
+        if not self._ping_func:
+            logger.error("Ping handler function is not set")
+            return Response(status_code=404)
+
+        try:
+            result = (
+                await self._ping_func()
+                if inspect.iscoroutinefunction(self._ping_func)
+                else self._ping_func()
+            )
+            payload = self._format_ping_status(result)
+            return JSONResponse(content=payload)
+        except Exception as e:
+            logger.exception("Ping handler function failed: %s", e)
+            return JSONResponse(
+                content={"status": "error", "message": str(e)},
+                status_code=500,
+            )
+
+    def add_env_detect_route(self, app: Starlette):
+        def is_agentkit_runtime() -> bool:
+            if os.getenv("RUNTIME_IAM_ROLE_TRN", ""):
+                return True
+            else:
+                return False
+
+        route = Route(
+            "/env",
+            endpoint=lambda request: JSONResponse(
+                {"env": "agentkit" if is_agentkit_runtime() else "veadk"}
+            ),
+            methods=["GET"],
+            name="env_detect",
+        )
+        app.routes.append(route)
+
+    def add_ping_route(self, app: Starlette):
+        app.add_route("/ping", self.ping_endpoint, methods=["GET"])
+
     @override
     def run(self, agent_card: AgentCard, host: str, port: int = 8000):
         if not self._agent_executor:
@@ -130,4 +201,8 @@ class AgentkitA2aApp(BaseAgentkitApp):
             ),
         ).build()
 
+        # Register routes in the same style
+        self.add_ping_route(a2a_app)
+        self.add_env_detect_route(a2a_app)
+
         uvicorn.run(a2a_app, host=host, port=port)

{agentkit_sdk_python-0.1.15 → agentkit_sdk_python-0.2.1}/agentkit/apps/agent_server_app/agent_server_app.py

@@ -19,6 +19,7 @@ import json
 from fastapi import Request
 from fastapi import HTTPException
 from fastapi.responses import StreamingResponse
+from opentelemetry import trace
 from google.adk.agents.base_agent import BaseAgent
 from google.adk.artifacts.in_memory_artifact_service import (
     InMemoryArtifactService,
@@ -41,6 +42,8 @@ from veadk import Agent
 from veadk.memory.short_term_memory import ShortTermMemory
 
 from agentkit.apps.base_app import BaseAgentkitApp
+from agentkit.apps.agent_server_app.telemetry import telemetry
+from agentkit.apps.agent_server_app.middleware import AgentkitTelemetryHTTPMiddleware
 
 
 class AgentKitAgentLoader(BaseAgentLoader):
@@ -87,7 +90,13 @@ class AgentkitAgentServerApp(BaseAgentkitApp):
 
         self.app = self.server.get_fast_api_app()
 
+        # Attach ASGI middleware for unified telemetry across all routes
+        self.app.add_middleware(AgentkitTelemetryHTTPMiddleware)
+
         async def _invoke_compat(request: Request):
+            # Use current request span from middleware for telemetry
+            span = trace.get_current_span()
+
             # Extract headers (fallback keys supported)
             headers = request.headers
             user_id = (
@@ -95,8 +104,7 @@ class AgentkitAgentServerApp(BaseAgentkitApp):
             )
             session_id = (
                 headers.get("session_id")
-                or headers.get("x-session-id")
-                or "agentkit_sample_session"
+                or ""
             )
 
             # Determine app_name from loader
@@ -126,6 +134,14 @@ class AgentkitAgentServerApp(BaseAgentkitApp):
                         text = ""
             content = types.UserContent(parts=[types.Part(text=text or "")])
 
+            # trace request attributes on current span
+            telemetry.trace_agent_server(
+                func_name="_invoke_compat",
+                span=span,
+                headers=dict(headers),
+                text=text or "",
+            )
+
             # Ensure session exists
             session = await self.server.session_service.get_session(
                 app_name=app_name, user_id=user_id, session_id=session_id
@@ -154,8 +170,11 @@ class AgentkitAgentServerApp(BaseAgentkitApp):
                                 )
                                 + "\n\n"
                             )
+                    # finish span on successful end of stream handled by middleware
+                    pass
                 except Exception as e:
                     yield f'data: {{"error": "{str(e)}"}}\n\n'
+                    telemetry.trace_agent_server_finish(func_result="", exception=e)
 
             return StreamingResponse(
                 event_generator(),

agentkit_sdk_python-0.2.1/agentkit/apps/agent_server_app/middleware.py

@@ -0,0 +1,75 @@
+# 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 typing import Callable
+
+from opentelemetry import trace
+from opentelemetry import context as context_api
+
+from agentkit.apps.agent_server_app.telemetry import telemetry
+
+_EXCLUDED_HEADERS = {"authorization", "token"}
+
+
+class AgentkitTelemetryHTTPMiddleware:
+    def __init__(self, app: Callable):
+        self.app = app
+
+    async def __call__(self, scope, receive, send):
+        print(f"test: {scope}")
+        if scope["type"] != "http":
+            return await self.app(scope, receive, send)
+
+        method = scope.get("method", "")
+        path = scope.get("path", "")
+        headers_list = scope.get("headers", [])
+        headers = {k.decode("latin-1"): v.decode("latin-1") for k, v in headers_list}
+        span = telemetry.tracer.start_span(name="agent_server_request")
+        ctx = trace.set_span_in_context(span)
+        context_api.attach(ctx)
+        headers = {
+            k: v for k, v in headers.items() if k.lower() not in _EXCLUDED_HEADERS
+        }
+
+        # Currently unable to retrieve user_id and session_id from headers; keep logic for future use
+        user_id = headers.get("user_id")
+        session_id = headers.get("session_id")
+        headers["user_id"] = user_id
+        headers["session_id"] = session_id
+        telemetry.trace_agent_server(
+            func_name=f"{method} {path}",
+            span=span,
+            headers=headers,
+            text="",  # do not consume body in middleware
+        )
+
+        async def send_wrapper(message):
+            try:
+                if message.get("type") == "http.response.body":
+                    more_body = message.get("more_body", False)
+                    if not more_body:
+                        telemetry.trace_agent_server_finish(
+                            path=path, func_result="", exception=None
+                        )
+                elif message.get("type") == "http.response.start":
+                    # could record status code if needed
+                    pass
+            finally:
+                await send(message)
+
+        try:
+            await self.app(scope, receive, send_wrapper)
+        except Exception as e:
+            telemetry.trace_agent_server_finish(path=path, func_result="", exception=e)
+            raise

agentkit_sdk_python-0.2.1/agentkit/apps/agent_server_app/telemetry.py

@@ -0,0 +1,130 @@
+# 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 logging
+import time
+from typing import Optional
+
+from opentelemetry import trace
+from opentelemetry.trace import get_tracer
+from opentelemetry.metrics import get_meter
+from opentelemetry.trace.span import Span
+
+from agentkit.apps.utils import safe_serialize_to_json_string
+
+_INVOKE_PATH = ["/run_sse", "/run", "/invoke"]
+
+_GEN_AI_CLIENT_OPERATION_DURATION_BUCKETS = [
+    0.01,
+    0.02,
+    0.04,
+    0.08,
+    0.16,
+    0.32,
+    0.64,
+    1.28,
+    2.56,
+    5.12,
+    10.24,
+    20.48,
+    40.96,
+    81.92,
+    163.84,
+]
+
+logger = logging.getLogger("agentkit." + __name__)
+
+
+class Telemetry:
+    def __init__(self):
+        self.tracer = get_tracer("agentkit.agent_server_app")
+        self.meter = get_meter("agentkit.agent_server_app")
+        self.latency_histogram = self.meter.create_histogram(
+            name="agentkit_runtime_operation_latency",
+            description="operation latency",
+            unit="s",
+            explicit_bucket_boundaries_advisory=_GEN_AI_CLIENT_OPERATION_DURATION_BUCKETS,
+        )
+
+    def trace_agent_server(
+        self,
+        func_name: str,
+        span: Span,
+        headers: dict,
+        text: str,
+    ) -> None:
+        span.set_attribute(key="gen_ai.system", value="agentkit")
+        span.set_attribute(key="gen_ai.func_name", value=func_name)
+
+        span.set_attribute(
+            key="gen_ai.request.headers",
+            value=safe_serialize_to_json_string(headers),
+        )
+
+        session_id = headers.get("session_id")
+        if session_id:
+            span.set_attribute(key="gen_ai.session.id", value=session_id)
+        user_id = headers.get("user_id")
+        if user_id:
+            span.set_attribute(key="gen_ai.user.id", value=user_id)
+
+        # Currently unable to retrieve input
+        # span.set_attribute(
+        #     key="gen_ai.input", value=safe_serialize_to_json_string(text)
+        # )
+
+        span.set_attribute(key="gen_ai.span.kind", value="agent_server")
+        span.set_attribute(key="gen_ai.operation.name", value="invoke_agent")
+        span.set_attribute(key="gen_ai.operation.type", value="agent_server")
+
+    def trace_agent_server_finish(
+        self,
+        path: str,
+        func_result: str,
+        exception: Optional[Exception],
+    ) -> None:
+        span = trace.get_current_span()
+        if span and span.is_recording():
+            # Currently unable to retrieve output
+            # span.set_attribute(key="gen_ai.output", value=func_result)
+
+            attributes = {
+                "gen_ai_operation_name": "invoke_agent",
+                "gen_ai_operation_type": "agent_server",
+            }
+            if exception:
+                self.handle_exception(span, exception)
+                attributes["error_type"] = exception.__class__.__name__
+
+            # only record invoke request latency metrics
+            if (
+                hasattr(span, "start_time")
+                and self.latency_histogram
+                and path in _INVOKE_PATH
+            ):
+                duration = (time.time_ns() - span.start_time) / 1e9  # type: ignore
+                self.latency_histogram.record(duration, attributes)
+            span.end()
+
+    @staticmethod
+    def handle_exception(span: trace.Span, exception: Exception) -> None:
+        status = trace.Status(
+            status_code=trace.StatusCode.ERROR,
+            description=f"{type(exception).__name__}: {exception}",
+        )
+        span.set_status(status)
+        span.record_exception(exception)
+
+
+telemetry = Telemetry()

{agentkit_sdk_python-0.1.15 → agentkit_sdk_python-0.2.1}/agentkit/apps/mcp_app/mcp_app.py

@@ -15,6 +15,7 @@
 
 import inspect
 import logging
+import os
 from functools import wraps
 from typing import Any, Callable, override
 
@@ -142,8 +143,25 @@ class AgentkitMCPApp(BaseAgentkitApp):
 
         return func
 
+    def add_env_detect_tool(self):
+        def is_agentkit_runtime() -> bool:
+            if os.getenv("RUNTIME_IAM_ROLE_TRN", ""):
+                return True
+            else:
+                return False
+
+        def get_env() -> dict:
+            return {"env": "agentkit" if is_agentkit_runtime() else "veadk"}
+
+        self._mcp_server.tool(get_env)
+
     @override
     def run(
-        self, host: str, port: int = 8000, transport: Transport = "streamable-http"
+        self,
+        host: str,
+        port: int = 8000,
+        transport: Transport = "streamable-http",
     ) -> None:
+        self.add_env_detect_tool()
+
         self._mcp_server.run(host=host, port=port, transport=transport)

{agentkit_sdk_python-0.1.15 → agentkit_sdk_python-0.2.1}/agentkit/client/base_agentkit_client.py

@@ -20,8 +20,7 @@ Provides common initialization and API invocation logic.
 from typing import Any, Dict, Union, Optional
 
 from agentkit.client.base_service_client import BaseServiceClient, ApiConfig
-from agentkit.utils.ve_sign import get_volc_agentkit_host_info
-from agentkit.toolkit.config.global_config import get_global_config
+from agentkit.utils.ve_sign import get_volc_agentkit_host_info, get_volc_agentkit_scheme
 
 
 class BaseAgentkitClient(BaseServiceClient):
@@ -78,13 +77,11 @@ class BaseAgentkitClient(BaseServiceClient):
             Dictionary with host, api_version, and service
         """
         host, api_version, service = get_volc_agentkit_host_info()
-        gc = get_global_config()
-        scheme = gc.agentkit_schema or "https"
         return {
-            "host": gc.agentkit_host or host,
+            "host": host,
             "api_version": api_version,
             "service": service,
-            "scheme": scheme,
+            "scheme": get_volc_agentkit_scheme(),
         }
 
     def _get(self, api_action: str, params: Dict[str, Any] = None) -> str:

{agentkit_sdk_python-0.1.15 → agentkit_sdk_python-0.2.1}/agentkit/client/base_iam_client.py

@@ -20,7 +20,7 @@ Uses the same volcengine.base.Service approach as AgentKit services.
 from typing import Dict, Union
 
 from agentkit.client.base_service_client import BaseServiceClient, ApiConfig
-from agentkit.toolkit.config.global_config import get_global_config
+from agentkit.utils.ve_sign import get_volc_iam_host_scheme
 
 
 class BaseIAMClient(BaseServiceClient):
@@ -79,11 +79,9 @@ class BaseIAMClient(BaseServiceClient):
         Returns:
             Dictionary with host, api_version, and service
         """
-        gc = get_global_config()
-        scheme = gc.iam_schema or "https"
-        host = gc.iam_host or self.IAM_HOST
+        host, scheme = get_volc_iam_host_scheme()
         return {
-            "host": host,
+            "host": host or self.IAM_HOST,
             "api_version": self.IAM_API_VERSION,
             "service": self.IAM_SERVICE_CODE,
             "scheme": scheme,

{agentkit_sdk_python-0.1.15 → agentkit_sdk_python-0.2.1}/agentkit/client/base_service_client.py

@@ -26,7 +26,10 @@ from volcengine.base.Service import Service
 from volcengine.Credentials import Credentials
 from volcengine.ServiceInfo import ServiceInfo
 
-from agentkit.utils.ve_sign import get_volc_ak_sk_region
+from agentkit.utils.ve_sign import (
+    get_volc_ak_sk_region,
+    ensure_x_custom_source_header,
+)
 
 T = TypeVar("T")
 
@@ -73,7 +76,7 @@ class BaseServiceClient(Service):
         session_token: str = "",
         service_name: str = "",
         credential_env_prefix: str = "",
-        header: Optional[Dict[str, Any]] = {"Accept": "application/json"},
+        header: Optional[Dict[str, Any]] = None,
     ) -> None:
         """
         Initialize the service client.
@@ -105,6 +108,15 @@ class BaseServiceClient(Service):
         self.session_token = session_token
         self.service_name = service_name
 
+        if header is None:
+            effective_header: Dict[str, Any] = {"Accept": "application/json"}
+        else:
+            effective_header = header.copy()
+            if "Accept" not in effective_header:
+                effective_header = {"Accept": "application/json", **effective_header}
+
+        effective_header = ensure_x_custom_source_header(effective_header)
+
         # Get service-specific configuration from subclass
         config = self._get_service_config()
         self.host = config["host"]
@@ -115,7 +127,7 @@ class BaseServiceClient(Service):
         # Create ServiceInfo
         self.service_info = ServiceInfo(
             host=self.host,
-            header=header,
+            header=effective_header,
             credentials=Credentials(
                 ak=self.access_key,
                 sk=self.secret_key,

{agentkit_sdk_python-0.1.15 → agentkit_sdk_python-0.2.1}/agentkit/sdk/knowledge/__init__.py

@@ -11,7 +11,7 @@
 # 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 .client import AgentkitKnowledge
+from .client import AgentkitKnowledgeClient
 from .types import (
     ListKnowledgeBasesRequest,
     ListKnowledgeBasesResponse,