agent-runtime-sdk 0.1.0__py3-none-any.whl

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/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/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",
+]

agent_runtime/config/definitions.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+"""框架的静态定义层。
+
+这个文件只负责“描述一个 agent runtime 长什么样”，不负责真正执行。
+调用链通常是：
+
+1. 先把 YAML / Builder 收敛成 AgentDefinition
+2. 再由 ManagedAgentRuntime 读取这些定义构造运行时
+3. 最后通过 standalone / builder 暴露成 A2A 服务
+"""
+
+import re
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+
+DEFAULT_PASS_THROUGH_HEADERS = ["X-Session-Id", "accessToken", "user_email"]
+DEFAULT_PLUGIN_MODULE_PATH = "agent_app/plugin.py"
+DEFAULT_PLUGIN_CLASS_NAME = "Plugin"
+
+
+class InputFieldDefinition(BaseModel):
+    """描述某个工具参数缺失时，需要向用户补采的字段。"""
+
+    name: str
+    type: str = "string"
+    description: str = ""
+    required: bool = True
+    default: Any = None
+    map_to_arg: str | None = None
+
+    @property
+    def target_arg(self) -> str:
+        return self.map_to_arg or self.name
+
+
+class ToolPolicy(BaseModel):
+    """工具治理策略。"""
+
+    enabled: bool = True
+    requires_confirmation: bool = False
+    input_fields: list[InputFieldDefinition] = Field(default_factory=list)
+    prompt: str | None = None
+    allow_arg_override: bool = True
+
+
+class ModelSettings(BaseModel):
+    """模型侧配置。"""
+
+    provider: str = "openai_compatible"
+    api_base: str | None = None
+    model_id: str | None = None
+    api_key_env: str = "MODEL_SOURCE_API_KEY"
+    max_steps: int = 15
+    flatten_messages_as_text: bool = True
+
+
+class MCPSettings(BaseModel):
+    """单个 MCP 服务的连接定义。"""
+
+    name: str
+    url: str
+    transport: str = "streamable-http"
+    enabled: bool = True
+    retry_count: int = Field(default=3, ge=0)
+    retry_delay_seconds: float = Field(default=1.0, ge=0)
+    static_headers: dict[str, str] = Field(default_factory=dict)
+    pass_through_headers: list[str] = Field(default_factory=lambda: list(DEFAULT_PASS_THROUGH_HEADERS))
+    # TODO: tool policy 后续还可以继续细分，不一定永远只挂在 MCP server 下。
+    tool_policies: dict[str, ToolPolicy] = Field(default_factory=dict)
+
+
+class PluginSettings(BaseModel):
+    """插件加载配置。"""
+
+    module_path: str = DEFAULT_PLUGIN_MODULE_PATH
+    class_name: str = DEFAULT_PLUGIN_CLASS_NAME
+    config: dict[str, Any] = Field(default_factory=dict)
+
+
+class SkillDefinition(BaseModel):
+    """A2A agent card 中对外暴露的一个技能描述。"""
+
+    id: str
+    name: str
+    description: str
+    tags: list[str] = Field(default_factory=list)
+    examples: list[str] = Field(default_factory=list)
+
+
+class A2ASettings(BaseModel):
+    """A2A 展示层配置。"""
+
+    skills: list[SkillDefinition] = Field(default_factory=list)
+    default_input_modes: list[str] = Field(default_factory=lambda: ["text"])
+    default_output_modes: list[str] = Field(default_factory=lambda: ["text"])
+
+
+class AgentConfig(BaseModel):
+    """Agent 的身份与展示配置。"""
+
+    agent_id: str
+    name: str
+    description: str
+    version: str = "0.1.0"
+    a2a: A2ASettings = Field(default_factory=A2ASettings)
+    extra_instructions: str = ""
+
+    @field_validator("agent_id")
+    @classmethod
+    def validate_agent_id(cls, value: str) -> str:
+        if not re.fullmatch(r"[a-zA-Z0-9][a-zA-Z0-9_-]*", value):
+            raise ValueError("agent_id must match [a-zA-Z0-9][a-zA-Z0-9_-]*")
+        return value
+
+
+class RuntimeConfig(BaseModel):
+    """运行时必要配置。"""
+
+    base_path: str = "."
+    public_base_url: str | None = None
+    model: ModelSettings
+    plugin: PluginSettings | None = None
+
+
+class AgentDefinition(BaseModel):
+    """一个 agent runtime 的完整静态定义。"""
+
+    agent: AgentConfig
+    runtime: RuntimeConfig
+    mcps: list[MCPSettings] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def validate_mcps(self) -> "AgentDefinition":
+        # FIXME: 未来不一定要求必须存在 MCP；当前先保持现有约束。
+        if not self.mcps:
+            raise ValueError("at least one MCP server must be configured in 'mcps'")
+
+        names = [mcp.name for mcp in self.mcps]
+        if len(set(names)) != len(names):
+            raise ValueError("mcp names must be unique")
+        return self

agent_runtime/config/policies.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .definitions import InputFieldDefinition, ToolPolicy
+
+
+def parse_user_payload(value: str | dict | None) -> Any:
+    if value is None:
+        return None
+    if isinstance(value, dict):
+        return value
+    text = str(value).strip()
+    if not text:
+        return None
+    try:
+        return json.loads(text)
+    except Exception:
+        return text
+
+
+def is_missing(value: Any) -> bool:
+    if value is None:
+        return True
+    if isinstance(value, str):
+        return value.strip() == ""
+    if isinstance(value, (list, dict)):
+        return len(value) == 0
+    return False
+
+
+def collect_missing_fields(policy: ToolPolicy, current_args: dict[str, Any]) -> list[InputFieldDefinition]:
+    missing: list[InputFieldDefinition] = []
+    for field in policy.input_fields:
+        target_arg = field.target_arg
+        if field.required and is_missing(current_args.get(target_arg)):
+            missing.append(field)
+    return missing
+
+
+def merge_input_fields(
+    current_args: dict[str, Any],
+    policy: ToolPolicy,
+    resume_payload: Any,
+) -> dict[str, Any]:
+    merged = dict(current_args)
+    if isinstance(resume_payload, dict):
+        for field in policy.input_fields:
+            key = field.name
+            target_arg = field.target_arg
+            if key in resume_payload and not is_missing(resume_payload[key]):
+                merged[target_arg] = resume_payload[key]
+            elif target_arg in resume_payload and not is_missing(resume_payload[target_arg]):
+                merged[target_arg] = resume_payload[target_arg]
+            elif field.default is not None and is_missing(merged.get(target_arg)):
+                merged[target_arg] = field.default
+        return merged
+
+    if len(policy.input_fields) == 1 and resume_payload is not None:
+        field = policy.input_fields[0]
+        merged[field.target_arg] = resume_payload
+    return merged