agentkit-sdk-python 0.1.5__py3-none-any.whl

agentkit/__init__.py

@@ -0,0 +1,23 @@
+# 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.
+
+# Note: BaseAgentkitClient and ApiConfig are internal infrastructure classes.
+# Users should use the high-level service clients instead:
+# - from agentkit.memory import AgentkitMemory
+# - from agentkit.knowledge import AgentkitKnowledge
+# - from agentkit.mcp import AgentkitMCP
+# - from agentkit.runtime import AgentkitRuntime
+# - from agentkit.tools import AgentkitTools
+
+__all__ = []

agentkit/apps/__init__.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.
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agentkit.apps.a2a_app.a2a_app import AgentkitA2aApp
+    from agentkit.apps.agent_server_app.agent_server_app import AgentkitAgentServerApp
+    from agentkit.apps.mcp_app.mcp_app import AgentkitMCPApp
+    from agentkit.apps.simple_app.simple_app import AgentkitSimpleApp
+
+
+def __getattr__(
+    name,
+) -> (
+    type["AgentkitA2aApp"]
+    | type["AgentkitMCPApp"]
+    | type["AgentkitSimpleApp"]
+    | type["AgentkitAgentServerApp"]
+):
+    if name == "AgentkitA2aApp":
+        from agentkit.apps.a2a_app.a2a_app import AgentkitA2aApp
+
+        return AgentkitA2aApp
+    if name == "AgentkitMCPApp":
+        from agentkit.apps.mcp_app.mcp_app import AgentkitMCPApp
+
+        return AgentkitMCPApp
+    if name == "AgentkitSimpleApp":
+        from agentkit.apps.simple_app.simple_app import AgentkitSimpleApp
+
+        return AgentkitSimpleApp
+    if name == "AgentkitAgentServerApp":
+        from agentkit.apps.agent_server_app.agent_server_app import (
+            AgentkitAgentServerApp,
+        )
+
+        return AgentkitAgentServerApp
+    raise AttributeError(f"module 'agentkit.apps' has no attribute '{name}'")
+
+
+__all__ = [
+    "AgentkitA2aApp",
+    "AgentkitMCPApp",
+    "AgentkitSimpleApp",
+    "AgentkitAgentServerApp",
+]

agentkit/apps/a2a_app/__init__.py

@@ -0,0 +1,13 @@
+# 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.

agentkit/apps/a2a_app/a2a_app.py

@@ -0,0 +1,134 @@
+# 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 Callable, override
+
+import uvicorn
+from a2a.server.agent_execution import AgentExecutor
+from a2a.server.agent_execution.context import RequestContext
+from a2a.server.apps import A2AStarletteApplication
+from a2a.server.events.event_queue import EventQueue
+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 agentkit.apps.base_app import BaseAgentkitApp
+from agentkit.apps.a2a_app.telemetry import telemetry
+
+logger = logging.getLogger(__name__)
+
+
+def _wrap_agent_executor_execute_func(execute_func: Callable) -> Callable:
+    async def wrapper(*args, **kwargs):
+        executor_instance: AgentExecutor = args[0]
+        context: RequestContext = args[1]
+        event_queue: EventQueue = args[2]
+
+        with telemetry.tracer.start_as_current_span(name="a2a_invocation") as span:
+            exception = None
+            try:
+                result = await execute_func(
+                    executor_instance, context=context, event_queue=event_queue
+                )
+
+            except Exception as e:
+                logger.error("Invoke agent execute function failed: %s", e)
+                exception = e
+                raise e
+            finally:
+                # handler trace span and metrics
+                telemetry.trace_a2a_agent(
+                    execute_func,
+                    span,
+                    context,
+                    result,
+                    exception,
+                )
+
+        return result
+
+    return wrapper
+
+
+class AgentkitA2aApp(BaseAgentkitApp):
+    def __init__(self) -> None:
+        super().__init__()
+
+        self._agent_executor: AgentExecutor | None = None
+        self._task_store: TaskStore | None = None
+
+    def agent_executor(self, **kwargs) -> Callable:
+        """Wrap an AgentExecutor class, init it, then bind it to the app instance."""
+
+        def wrapper(cls: type) -> type[AgentExecutor]:
+            if not issubclass(cls, AgentExecutor):
+                raise TypeError(
+                    f"{cls.__name__} must inherit from `a2a.server.agent_execution.AgentExecutor`"
+                )
+
+            if self._agent_executor:
+                raise RuntimeError("An executor is already bound to this app instance.")
+
+            # Wrap the execute method for intercepting context and event_queue
+            cls.execute = _wrap_agent_executor_execute_func(cls.execute)
+
+            # Initialize and bind the executor instance
+            self._agent_executor = cls(**kwargs)
+
+            return cls
+
+        return wrapper
+
+    def task_store(self, **kwargs) -> Callable:
+        """Wrap a TaskStore class, init it, then bind it to the app instance."""
+
+        def wrapper(cls: type) -> type[TaskStore]:
+            if not issubclass(cls, TaskStore):
+                raise TypeError(
+                    f"{cls.__name__} must inherit from `a2a.server.tasks.task_store.TaskStore`"
+                )
+
+            if self._task_store:
+                raise RuntimeError(
+                    "A task store is already bound to this app instance."
+                )
+
+            self._task_store = cls(**kwargs)
+            return cls
+
+        return wrapper
+
+    @override
+    def run(self, agent_card: AgentCard, host: str, port: int = 8000):
+        if not self._agent_executor:
+            raise RuntimeError(
+                "At least one executor should be provided via `@agent_executor(...)`."
+            )
+        if not self._task_store:
+            logger.warning(
+                "No task store provided. You can provide a task store via `@task_store(...)`. Using in-memory task store instead."
+            )
+            self._task_store = InMemoryTaskStore()
+
+        a2a_app = A2AStarletteApplication(
+            agent_card=agent_card,
+            http_handler=DefaultRequestHandler(
+                agent_executor=self._agent_executor, task_store=self._task_store
+            ),
+        ).build()
+
+        uvicorn.run(a2a_app, host=host, port=port)

agentkit/apps/a2a_app/telemetry.py

@@ -0,0 +1,119 @@
+# 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 Callable
+
+from opentelemetry import trace
+from opentelemetry.trace import get_tracer
+from opentelemetry.metrics import get_meter
+from opentelemetry.trace.span import Span
+from a2a.server.agent_execution.context import RequestContext
+from google.adk.a2a.converters.request_converter import _get_user_id
+
+from agentkit.apps.utils import safe_serialize_to_json_string
+
+_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.a2a_app")
+        self.meter = get_meter("agentkit.a2a_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_a2a_agent(
+        self,
+        func: Callable,
+        span: Span,
+        request: RequestContext,
+        result: any,
+        exception: Exception,
+    ) -> None:
+        """Get current span and set required attributes."""
+        trace_id = span.get_span_context().trace_id
+        span_id = span.get_span_context().span_id
+        logger.debug(f"Set attributes for span with trace_id={trace_id}, span_id={span_id}")
+
+        # ===============================
+        # Set attributes for current span
+        # ===============================
+
+        span.set_attribute(key="gen_ai.system", value="agentkit")
+
+        span.set_attribute(key="gen_ai.func_name", value=func.__name__)
+
+        # TODO:  get user_id and session_id, output from event queue
+        session_id = request.context_id
+        if session_id:
+            span.set_attribute(key="gen_ai.session.id", value=session_id)
+        user_id = _get_user_id(request)
+        if user_id:
+            span.set_attribute(key="gen_ai.user.id", value=user_id)
+
+        span.set_attribute(key="gen_ai.input", value=safe_serialize_to_json_string(request.message.parts))
+
+        span.set_attribute(key="gen_ai.span.kind", value="a2a_agent")
+        span.set_attribute(key="gen_ai.operation.name", value="invoke_agent")
+        span.set_attribute(key="gen_ai.operation.type", value="a2a_agent")
+        attributes={"gen_ai_operation_name": "invoke_agent", "gen_ai_operation_type": "a2a_agent"}
+
+        if exception:
+            self.handle_exception(span, exception)
+            attributes["error_type"] = exception.__class__.__name__
+
+        # record latency metrics
+        if hasattr(span, "start_time") and self.latency_histogram:
+            duration = (time.time_ns() - span.start_time) / 1e9  # type: ignore
+            self.latency_histogram.record(duration, attributes)
+
+    @staticmethod
+    def handle_exception(span: trace.Span, exception: Exception) -> None:
+        status = trace.Status(
+            status_code=trace.StatusCode.ERROR,
+            # Follow the format in OTEL SDK for description, see:
+            # https://github.com/open-telemetry/opentelemetry-python/blob/2b9dcfc5d853d1c10176937a6bcaade54cda1a31/opentelemetry-api/src/opentelemetry/trace/__init__.py#L588  # noqa E501
+            description=f"{type(exception).__name__}: {exception}",
+        )
+        span.set_status(status)
+        span.record_exception(exception)
+
+
+telemetry = Telemetry()
+

agentkit/apps/agent_server_app/__init__.py

@@ -0,0 +1,13 @@
+# 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.

agentkit/apps/agent_server_app/agent_server_app.py

@@ -0,0 +1,85 @@
+# 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 override
+
+import uvicorn
+from google.adk.agents.base_agent import BaseAgent
+from google.adk.artifacts.in_memory_artifact_service import (
+    InMemoryArtifactService,
+)
+from google.adk.auth.credential_service.in_memory_credential_service import (
+    InMemoryCredentialService,
+)
+from google.adk.cli.adk_web_server import AdkWebServer
+from google.adk.cli.utils.base_agent_loader import BaseAgentLoader
+from google.adk.evaluation.local_eval_set_results_manager import (
+    LocalEvalSetResultsManager,
+)
+from google.adk.evaluation.local_eval_sets_manager import LocalEvalSetsManager
+from google.adk.memory.in_memory_memory_service import InMemoryMemoryService
+from google.adk.sessions.base_session_service import BaseSessionService
+from veadk import Agent
+from veadk.memory.short_term_memory import ShortTermMemory
+
+from agentkit.apps.base_app import BaseAgentkitApp
+
+
+class AgentKitAgentLoader(BaseAgentLoader):
+    def __init__(self, agent: BaseAgent) -> None:
+        super().__init__()
+
+        self.agent = agent
+
+    @override
+    def load_agent(self, agent_name: str) -> BaseAgent:
+        return self.agent
+
+    @override
+    def list_agents(self) -> list[str]:
+        return [self.agent.name]
+
+
+class AgentkitAgentServerApp(BaseAgentkitApp):
+    def __init__(
+        self, agent: BaseAgent, short_term_memory: BaseSessionService | ShortTermMemory
+    ) -> None:
+        super().__init__()
+
+        _artifact_service = InMemoryArtifactService()
+        _credential_service = InMemoryCredentialService()
+
+        _eval_sets_manager = LocalEvalSetsManager(agents_dir=".")
+        _eval_set_results_manager = LocalEvalSetResultsManager(agents_dir=".")
+
+        self.server = AdkWebServer(
+            agent_loader=AgentKitAgentLoader(agent),
+            session_service=short_term_memory
+            if isinstance(short_term_memory, BaseSessionService)
+            else short_term_memory.session_service,
+            memory_service=agent.long_term_memory
+            if isinstance(agent, Agent) and agent.long_term_memory
+            else InMemoryMemoryService(),
+            artifact_service=_artifact_service,
+            credential_service=_credential_service,
+            eval_sets_manager=_eval_sets_manager,
+            eval_set_results_manager=_eval_set_results_manager,
+            agents_dir=".",
+        )
+
+        self.app = self.server.get_fast_api_app()
+
+    def run(self, host: str, port: int = 8000) -> None:
+        """Run the app with Uvicorn server."""
+        uvicorn.run(self.app, host=host, port=port)

agentkit/apps/base_app.py

@@ -0,0 +1,20 @@
+# 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 abc import ABC, abstractmethod
+
+
+class BaseAgentkitApp(ABC):
+    @abstractmethod
+    def run(self, **kwargs): ...

agentkit/apps/mcp_app/__init__.py

@@ -0,0 +1,13 @@
+# 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.

agentkit/apps/mcp_app/mcp_app.py

@@ -0,0 +1,150 @@
+# 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 inspect
+import logging
+import time
+from functools import wraps
+from typing import Any, Callable, override
+
+from fastmcp import FastMCP
+from fastmcp.server.server import Transport
+
+from agentkit.apps.base_app import BaseAgentkitApp
+from agentkit.apps.mcp_app.telemetry import telemetry
+
+logger = logging.getLogger(__name__)
+
+
+class AgentkitMCPApp(BaseAgentkitApp):
+    def __init__(self) -> None:
+        super().__init__()
+
+        self._mcp_server = FastMCP("agentkit.mcp_server")
+
+    def tool(self, func: Callable) -> Callable:
+        if inspect.iscoroutinefunction(func):
+
+            @wraps(func)
+            async def async_wrapper(*args, **kwargs) -> Any:
+                # with tracer.start_as_current_span("tool") as span:
+                with telemetry.tracer.start_as_current_span(name="tool") as span:
+                    exception = None
+                    try:
+                        result = await func(*args, **kwargs)
+
+                    except Exception as e:
+                        logger.error("Invoke tool function failed: %s", e)
+                        exception = e
+                        raise e
+                    finally:
+                        # handler trace span and metrics
+                        telemetry.trace_tool(
+                            func,
+                            span,
+                            args,
+                            func_result=result,
+                            operation_type="mcp_tool",
+                            exception=exception,
+                        )
+
+                return result
+
+            self._mcp_server.tool(async_wrapper)
+        else:
+
+            @wraps(func)
+            def sync_wrapper(*args, **kwargs) -> Any:
+                # with tracer.start_as_current_span("tool") as span:
+                with telemetry.tracer.start_as_current_span(name="tool") as span:
+                    exception = None
+                    try:
+                        result = func(*args, **kwargs)
+                    except Exception as e:
+                        logger.error("Invoke tool function failed: %s", e)
+                        exception = e
+                        raise e
+                    finally:
+                        telemetry.trace_tool(
+                            func,
+                            span,
+                            args,
+                            func_result=result,
+                            operation_type="mcp_tool",
+                            exception=exception,
+                        )
+                return result
+
+            self._mcp_server.tool(sync_wrapper)
+
+        return func
+
+    def agent_as_a_tool(self, func: Callable) -> Callable:
+        if inspect.iscoroutinefunction(func):
+
+            @wraps(func)
+            async def async_wrapper(*args, **kwargs) -> Any:
+                with telemetry.tracer.start_as_current_span(name="tool") as span:
+                    exception = None
+                    try:
+                        result = await func(*args, **kwargs)
+                    except Exception as e:
+                        logger.error("Invoke tool function failed: %s", e)
+                        exception = e
+                        raise e
+                    finally:
+                        telemetry.trace_tool(
+                            func,
+                            span,
+                            args=args,
+                            func_result=result,
+                            operation_type="agent_mcp_tool",
+                            exception=exception,
+                        )
+                return result
+
+            self._mcp_server.tool(async_wrapper)
+        else:
+
+            @wraps(func)
+            def sync_wrapper(*args, **kwargs) -> Any:
+                with telemetry.tracer.start_as_current_span(name="tool") as span:
+                    exception = None
+                    try:
+                        result = func(*args, **kwargs)
+                    except Exception as e:
+                        logger.error("Invoke tool function failed: %s", e)
+                        exception = e
+                        raise e
+                    finally:
+                        telemetry.trace_tool(
+                            func,
+                            span,
+                            args,
+                            func_result=result,
+                            operation_type="agent_mcp_tool",
+                            exception=exception,
+                        )
+                return result
+
+            self._mcp_server.tool(sync_wrapper)
+
+        return func
+
+    @override
+    def run(
+        self, host: str, port: int = 8000, transport: Transport = "streamable-http"
+    ) -> None:
+        self._mcp_server.run(host=host, port=port, transport=transport)