agent-runtime-sdk 0.1.0__tar.gz

agent_runtime_sdk-0.1.0/MANIFEST.in

@@ -0,0 +1,12 @@
+include README_PACKAGE.md
+include pyproject.toml
+recursive-include agent_runtime *.py
+recursive-exclude agent_app *
+recursive-exclude tests *
+global-exclude __pycache__
+global-exclude *.py[cod]
+exclude README.md
+exclude Dockerfile
+exclude CSK_AGENT_API_FLOW.md
+exclude main.py
+exclude requirements.txt

agent_runtime_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: agent-runtime-sdk
+Version: 0.1.0
+Summary: Single-agent runtime SDK for A2A agents backed by MCP tools.
+Project-URL: Homepage, https://pypi.org/project/agent-runtime-sdk/
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: a2a-sdk==0.3.22
+Requires-Dist: smolagents[mcp]
+Requires-Dist: openai
+Requires-Dist: fastapi
+Requires-Dist: uvicorn
+Requires-Dist: httpx
+Requires-Dist: jinja2
+Requires-Dist: pyyaml
+Requires-Dist: loguru
+Requires-Dist: pydantic
+Requires-Dist: rich
+Provides-Extra: observability
+Requires-Dist: langfuse; extra == "observability"
+Requires-Dist: openinference-instrumentation-smolagents; extra == "observability"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+# agent-runtime-sdk
+
+Single-agent runtime SDK for exposing MCP tools as an A2A-compatible agent service.
+
+## Install
+
+```bash
+pip install agent-runtime-sdk
+```
+
+Install optional Langfuse/smolagents observability support:
+
+```bash
+pip install "agent-runtime-sdk[observability]"
+```
+
+## Basic Usage
+
+Create an agent project:
+
+```text
+my-agent/
+├── agent_app/
+│   ├── agent.yaml
+│   └── plugin.py
+└── main.py
+```
+
+Example `main.py`:
+
+```python
+from pathlib import Path
+
+from agent_runtime.standalone import build_single_agent_app, run_single_agent_app
+
+
+app = build_single_agent_app(
+    Path(__file__).resolve().parent / "agent_app" / "agent.yaml"
+)
+
+
+if __name__ == "__main__":
+    run_single_agent_app(app)
+```
+
+Example SDK import:
+
+```python
+from agent_runtime import AgentBuilder
+```
+
+## Minimal Configuration
+
+Example `agent_app/agent.yaml`:
+
+```yaml
+agent:
+  agent_id: example-agent
+  name: Example Agent
+  description: Example A2A agent backed by MCP tools.
+
+runtime:
+  public_base_url: ${AGENT_PUBLIC_BASE_URL:-http://127.0.0.1:10020}
+  model:
+    provider: openai_compatible
+    api_base: ${MODEL_SOURCE_API_BASE}
+    model_id: ${MODEL_SOURCE_MODEL_ID}
+    api_key_env: MODEL_SOURCE_API_KEY
+
+mcps:
+  - name: example
+    url: ${MCP_EXAMPLE_URL}
+    transport: streamable-http
+```
+
+Run:
+
+```bash
+export MODEL_SOURCE_API_BASE="https://your-model-api.example.com"
+export MODEL_SOURCE_MODEL_ID="your-model-id"
+export MODEL_SOURCE_API_KEY="your-api-key"
+export MCP_EXAMPLE_URL="http://127.0.0.1:8000/mcp"
+export AGENT_PUBLIC_BASE_URL="http://127.0.0.1:10020"
+
+python main.py
+```
+
+## Langfuse
+
+After installing `agent-runtime-sdk[observability]`, configure:
+
+```bash
+export MCP_AGENT_LANGFUSE_ENABLED=true
+export LANGFUSE_BASE_URL="http://your-langfuse-host:3000"
+export LANGFUSE_PUBLIC_KEY="pk-lf-..."
+export LANGFUSE_SECRET_KEY="sk-lf-..."
+```
+
+Set `MCP_AGENT_LANGFUSE_ENABLED=false` to disable instrumentation.

agent_runtime_sdk-0.1.0/README_PACKAGE.md

@@ -0,0 +1,99 @@
+# agent-runtime-sdk
+
+Single-agent runtime SDK for exposing MCP tools as an A2A-compatible agent service.
+
+## Install
+
+```bash
+pip install agent-runtime-sdk
+```
+
+Install optional Langfuse/smolagents observability support:
+
+```bash
+pip install "agent-runtime-sdk[observability]"
+```
+
+## Basic Usage
+
+Create an agent project:
+
+```text
+my-agent/
+├── agent_app/
+│   ├── agent.yaml
+│   └── plugin.py
+└── main.py
+```
+
+Example `main.py`:
+
+```python
+from pathlib import Path
+
+from agent_runtime.standalone import build_single_agent_app, run_single_agent_app
+
+
+app = build_single_agent_app(
+    Path(__file__).resolve().parent / "agent_app" / "agent.yaml"
+)
+
+
+if __name__ == "__main__":
+    run_single_agent_app(app)
+```
+
+Example SDK import:
+
+```python
+from agent_runtime import AgentBuilder
+```
+
+## Minimal Configuration
+
+Example `agent_app/agent.yaml`:
+
+```yaml
+agent:
+  agent_id: example-agent
+  name: Example Agent
+  description: Example A2A agent backed by MCP tools.
+
+runtime:
+  public_base_url: ${AGENT_PUBLIC_BASE_URL:-http://127.0.0.1:10020}
+  model:
+    provider: openai_compatible
+    api_base: ${MODEL_SOURCE_API_BASE}
+    model_id: ${MODEL_SOURCE_MODEL_ID}
+    api_key_env: MODEL_SOURCE_API_KEY
+
+mcps:
+  - name: example
+    url: ${MCP_EXAMPLE_URL}
+    transport: streamable-http
+```
+
+Run:
+
+```bash
+export MODEL_SOURCE_API_BASE="https://your-model-api.example.com"
+export MODEL_SOURCE_MODEL_ID="your-model-id"
+export MODEL_SOURCE_API_KEY="your-api-key"
+export MCP_EXAMPLE_URL="http://127.0.0.1:8000/mcp"
+export AGENT_PUBLIC_BASE_URL="http://127.0.0.1:10020"
+
+python main.py
+```
+
+## Langfuse
+
+After installing `agent-runtime-sdk[observability]`, configure:
+
+```bash
+export MCP_AGENT_LANGFUSE_ENABLED=true
+export LANGFUSE_BASE_URL="http://your-langfuse-host:3000"
+export LANGFUSE_PUBLIC_KEY="pk-lf-..."
+export LANGFUSE_SECRET_KEY="sk-lf-..."
+```
+
+Set `MCP_AGENT_LANGFUSE_ENABLED=false` to disable instrumentation.

agent_runtime_sdk-0.1.0/agent_runtime/__init__.py

@@ -0,0 +1,84 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from .builder import AgentBuilder
+from .definitions import (
+    A2ASettings,
+    AgentConfig,
+    AgentDefinition,
+    InputFieldDefinition,
+    MCPSettings,
+    ModelSettings,
+    PluginSettings,
+    RuntimeConfig,
+    SkillDefinition,
+    ToolPolicy,
+)
+from .discovery import DiscoveredTool
+from .exceptions import (
+    AgentBuildError,
+    AgentRuntimeError,
+    DefinitionLoadError,
+    MCPToolLoadError,
+    PluginLoadError,
+    TaskCancelledError,
+    TaskWaitTimeoutError,
+    UserCancelledError,
+)
+from .model_registry import ModelRegistry
+from .plugins.base import BaseAgentPlugin, BeforeToolDecision, ToolExecutionContext
+from .plugins.default import DefaultPlugin
+from .runtime import ManagedAgentRuntime
+from .sdk_agent import (
+    BaseSDKAgent,
+    ConfiguredSDKAgent,
+    DeclarativeSDKAgent,
+    OpenAICompatibleSingleMCPAgent,
+    SingleMCPAgent,
+)
+from .server.bootstrap import load_single_agent_runtime
+from .standalone import build_single_agent_app, run_single_agent_app
+from .storage import AgentDefinitionStore
+
+try:
+    __version__ = version("agent-runtime-sdk")
+except PackageNotFoundError:  # pragma: no cover - source tree without installed metadata
+    __version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "A2ASettings",
+    "AgentConfig",
+    "AgentBuilder",
+    "AgentBuildError",
+    "AgentDefinition",
+    "AgentDefinitionStore",
+    "AgentRuntimeError",
+    "BaseAgentPlugin",
+    "BaseSDKAgent",
+    "ConfiguredSDKAgent",
+    "DeclarativeSDKAgent",
+    "BeforeToolDecision",
+    "DefinitionLoadError",
+    "DefaultPlugin",
+    "InputFieldDefinition",
+    "MCPToolLoadError",
+    "MCPSettings",
+    "ManagedAgentRuntime",
+    "ModelSettings",
+    "ModelRegistry",
+    "OpenAICompatibleSingleMCPAgent",
+    "PluginSettings",
+    "PluginLoadError",
+    "RuntimeConfig",
+    "SkillDefinition",
+    "SingleMCPAgent",
+    "TaskCancelledError",
+    "TaskWaitTimeoutError",
+    "DiscoveredTool",
+    "ToolExecutionContext",
+    "ToolPolicy",
+    "UserCancelledError",
+    "build_single_agent_app",
+    "load_single_agent_runtime",
+    "run_single_agent_app",
+]

agent_runtime_sdk-0.1.0/agent_runtime/builder.py

@@ -0,0 +1,317 @@
+from __future__ import annotations
+
+"""面向使用者的代码式构建入口。"""
+
+import os
+import re
+from pathlib import Path
+from typing import Any, Callable
+from urllib.parse import urlparse
+
+from .config.definitions import (
+    DEFAULT_PASS_THROUGH_HEADERS,
+    AgentConfig,
+    AgentDefinition,
+    InputFieldDefinition,
+    MCPSettings,
+    ModelSettings,
+    PluginSettings,
+    RuntimeConfig,
+    SkillDefinition,
+    ToolPolicy,
+)
+from .mcp.metadata import DiscoveredTool
+from .plugins.base import BaseAgentPlugin
+from .runtime import ManagedAgentRuntime
+
+
+class AgentBuilder:
+    """代码式配置入口。"""
+
+    def __init__(self):
+        self._agent = AgentConfig(
+            agent_id="mcp_agent",
+            name="",
+            description="",
+            version="0.1.0",
+        )
+        self._runtime = RuntimeConfig(
+            base_path=".",
+            public_base_url=None,
+            model=ModelSettings(),
+        )
+        self._mcps: list[MCPSettings] = []
+
+        self._plugin_instance: BaseAgentPlugin | None = None
+        self._discoverer: Callable[..., list[DiscoveredTool]] | None = None
+        self._explicit_model_api_key: str | None = None
+        self._auto_agent_id = True
+
+    def model(
+        self,
+        *,
+        provider: str | None = None,
+        api_base: str | None = None,
+        model_id: str | None = None,
+        api_key: str | None = None,
+        api_key_env: str | None = None,
+        max_steps: int | None = None,
+        flatten_messages_as_text: bool | None = None,
+    ) -> AgentBuilder:
+        model = self._runtime.model
+        if provider is not None:
+            model.provider = provider
+        if api_base is not None:
+            model.api_base = api_base
+        if model_id is not None:
+            model.model_id = model_id
+        if api_key is not None:
+            self._explicit_model_api_key = api_key
+        if api_key_env is not None:
+            model.api_key_env = api_key_env
+        if max_steps is not None:
+            model.max_steps = max_steps
+        if flatten_messages_as_text is not None:
+            model.flatten_messages_as_text = flatten_messages_as_text
+        return self
+
+    def tool_policy(
+        self,
+        tool_name: str,
+        *,
+        mcp_name: str | None = None,
+        requires_confirmation: bool = False,
+        prompt: str | None = None,
+        enabled: bool = True,
+        allow_arg_override: bool = True,
+        input_fields: list[InputFieldDefinition | dict[str, Any]] | None = None,
+    ) -> AgentBuilder:
+        fields: list[InputFieldDefinition] = []
+        if input_fields:
+            for field in input_fields:
+                if isinstance(field, InputFieldDefinition):
+                    fields.append(field)
+                else:
+                    fields.append(InputFieldDefinition.model_validate(field))
+        target_mcp = self._resolve_policy_target_mcp(mcp_name)
+        target_mcp.tool_policies[tool_name] = ToolPolicy(
+            enabled=enabled,
+            requires_confirmation=requires_confirmation,
+            input_fields=fields,
+            prompt=prompt,
+            allow_arg_override=allow_arg_override,
+        )
+        return self
+
+    def plugin(self, plugin: BaseAgentPlugin) -> AgentBuilder:
+        self._plugin_instance = plugin
+        return self
+
+    def instructions(self, text: str) -> AgentBuilder:
+        self._agent.extra_instructions = text
+        return self
+
+    def max_steps(self, n: int) -> AgentBuilder:
+        self._runtime.model.max_steps = n
+        return self
+
+    def agent_info(
+        self,
+        *,
+        agent_id: str | None = None,
+        name: str | None = None,
+        description: str | None = None,
+        version: str | None = None,
+    ) -> AgentBuilder:
+        if agent_id is not None:
+            self._agent.agent_id = agent_id
+            self._auto_agent_id = False
+        if name is not None:
+            self._agent.name = name
+        if description is not None:
+            self._agent.description = description
+        if version is not None:
+            self._agent.version = version
+        return self
+
+    def add_mcp(
+        self,
+        *,
+        name: str,
+        url: str,
+        transport: str = "streamable-http",
+        enabled: bool = True,
+        retry_count: int = 3,
+        retry_delay_seconds: float = 1.0,
+        static_headers: dict[str, str] | None = None,
+        pass_through_headers: list[str] | None = None,
+        tool_policies: dict[str, ToolPolicy | dict[str, Any]] | None = None,
+    ) -> AgentBuilder:
+        policies: dict[str, ToolPolicy] = {}
+        if tool_policies:
+            for tool_name, policy in tool_policies.items():
+                policies[tool_name] = (
+                    policy
+                    if isinstance(policy, ToolPolicy)
+                    else ToolPolicy.model_validate(policy)
+                )
+        self._mcps.append(
+            MCPSettings(
+                name=name,
+                url=url,
+                transport=transport,
+                enabled=enabled,
+                retry_count=retry_count,
+                retry_delay_seconds=retry_delay_seconds,
+                static_headers=static_headers or {},
+                pass_through_headers=pass_through_headers
+                or list(DEFAULT_PASS_THROUGH_HEADERS),
+                tool_policies=policies,
+            )
+        )
+        return self
+
+    def a2a_skill(
+        self,
+        *,
+        id: str,
+        name: str,
+        description: str,
+        tags: list[str] | None = None,
+        examples: list[str] | None = None,
+    ) -> AgentBuilder:
+        self._agent.a2a.skills.append(
+            SkillDefinition(
+                id=id,
+                name=name,
+                description=description,
+                tags=tags or [],
+                examples=examples or [],
+            )
+        )
+        return self
+
+    def public_base_url(self, url: str) -> AgentBuilder:
+        self._runtime.public_base_url = url
+        return self
+
+    def discoverer(self, func: Callable[..., list[DiscoveredTool]]) -> AgentBuilder:
+        self._discoverer = func
+        return self
+
+    def build(self) -> ManagedAgentRuntime:
+        definition = self.build_definition()
+        if self._explicit_model_api_key is not None:
+            os.environ[definition.runtime.model.api_key_env] = (
+                self._explicit_model_api_key
+            )
+
+        runtime = ManagedAgentRuntime(
+            definition=definition,
+            public_base_url=definition.runtime.public_base_url or "",
+            discoverer=self._discoverer,
+        )
+        if self._plugin_instance is not None:
+            runtime.plugin = self._plugin_instance
+            runtime.reload(discover=True, skip_plugin_load=True)
+        else:
+            runtime.reload(discover=True)
+        if runtime.load_error:
+            raise RuntimeError(runtime.load_error)
+        return runtime
+
+    def build_a2a_app(
+        self, *, public_url: str | None = None, enable_management: bool = True
+    ):
+        from .server.app_factory import build_app_from_runtime
+
+        if public_url is not None:
+            self.public_base_url(public_url)
+        runtime = self.build()
+        return build_app_from_runtime(runtime, enable_management=enable_management)
+
+    @classmethod
+    def from_yaml(cls, path: str | Path) -> AgentBuilder:
+        from .config.storage import AgentDefinitionStore
+
+        resolved = Path(path).resolve()
+        definition = AgentDefinitionStore(resolved.parent).load_path(resolved)
+        return cls.from_definition(definition)
+
+    @classmethod
+    def from_definition(cls, definition: AgentDefinition) -> AgentBuilder:
+        builder = cls()
+        builder._agent = definition.agent.model_copy(deep=True)
+        builder._runtime = definition.runtime.model_copy(deep=True)
+        builder._mcps = [mcp.model_copy(deep=True) for mcp in definition.mcps]
+        builder._auto_agent_id = False
+        return builder
+
+    def build_definition(self) -> AgentDefinition:
+        """返回当前 builder 收敛后的 `AgentDefinition`。
+
+        这个方法适合：
+
+        - 需要在真正 `build()` 前检查最终配置
+        - Python SDK 层希望把 YAML / 类配置统一收敛到同一个 definition 规格
+        """
+
+        if not self._mcps:
+            raise ValueError("at least one MCP server must be added before build()")
+
+        agent = self._agent.model_copy(deep=True)
+        runtime = self._runtime.model_copy(deep=True)
+        mcps = [mcp.model_copy(deep=True) for mcp in self._mcps]
+
+        if self._auto_agent_id:
+            agent.agent_id = self._auto_agent_id_from_mcps(mcps)
+        if not agent.name:
+            agent.name = agent.agent_id
+        if not agent.description:
+            agent.description = agent.name
+
+        if runtime.model.api_base is None:
+            runtime.model.api_base = os.getenv("MODEL_SOURCE_API_BASE")
+        if runtime.model.model_id is None:
+            runtime.model.model_id = os.getenv("MODEL_SOURCE_MODEL_ID")
+
+        if self._plugin_instance is not None:
+            runtime.plugin = None
+
+        return AgentDefinition(
+            agent=agent,
+            runtime=runtime,
+            mcps=mcps,
+        )
+
+    def _build_definition(self) -> AgentDefinition:
+        """兼容旧内部调用；新代码请优先使用 `build_definition()`。"""
+
+        return self.build_definition()
+
+    @staticmethod
+    def _auto_agent_id_from_mcps(mcps: list[MCPSettings]) -> str:
+        parsed = urlparse(mcps[0].url)
+        path_part = (
+            parsed.path.strip("/").split("/")[-1] if parsed.path.strip("/") else ""
+        )
+        if path_part:
+            normalized = re.sub(r"[^0-9a-zA-Z_]", "_", path_part)
+            return f"mcp_{normalized}" if normalized else "mcp_agent"
+        return "mcp_agent"
+
+    def _resolve_policy_target_mcp(self, mcp_name: str | None) -> MCPSettings:
+        if mcp_name is not None:
+            for mcp in self._mcps:
+                if mcp.name == mcp_name:
+                    return mcp
+            raise ValueError(f"mcp '{mcp_name}' not found")
+        if len(self._mcps) == 1:
+            return self._mcps[0]
+        if not self._mcps:
+            raise ValueError(
+                "add an MCP before tool_policy(), or pass mcp_name after configuring MCPs"
+            )
+        raise ValueError(
+            "multiple MCPs configured; please specify mcp_name when setting tool_policy()"
+        )

agent_runtime_sdk-0.1.0/agent_runtime/config/__init__.py

@@ -0,0 +1,29 @@
+"""配置层内部实现。"""
+
+from .definitions import (
+    A2ASettings,
+    AgentConfig,
+    AgentDefinition,
+    InputFieldDefinition,
+    MCPSettings,
+    ModelSettings,
+    PluginSettings,
+    RuntimeConfig,
+    SkillDefinition,
+    ToolPolicy,
+)
+from .storage import AgentDefinitionStore
+
+__all__ = [
+    "A2ASettings",
+    "AgentConfig",
+    "AgentDefinition",
+    "AgentDefinitionStore",
+    "InputFieldDefinition",
+    "MCPSettings",
+    "ModelSettings",
+    "PluginSettings",
+    "RuntimeConfig",
+    "SkillDefinition",
+    "ToolPolicy",
+]