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

agent_runtime/config/storage.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+"""definition 的持久化与环境变量展开。"""
+
+import logging
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .definitions import AgentDefinition
+from ..exceptions import DefinitionLoadError
+
+logger = logging.getLogger(__name__)
+
+
+_ENV_PATTERN = re.compile(r"\$\{(?P<name>[A-Z0-9_]+)(?::-(?P<default>[^}]*))?\}")
+
+
+def _resolve_env_placeholders(value: Any) -> Any:
+    """递归展开 YAML 中的 ${ENV} / ${ENV:-default} 占位符。"""
+    if isinstance(value, dict):
+        return {k: _resolve_env_placeholders(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_resolve_env_placeholders(v) for v in value]
+    if not isinstance(value, str):
+        return value
+
+    def _replace(match: re.Match[str]) -> str:
+        name = match.group("name")
+        default = match.group("default")
+        return os.getenv(name, default or "")
+
+    return _ENV_PATTERN.sub(_replace, value)
+
+
+def _default_base_root(definition_path: Path) -> Path:
+    """约定：如果 definition 放在 agent_app/ 下，默认相对项目根目录解析。"""
+    if definition_path.parent.name == "agent_app":
+        return definition_path.parent.parent
+    return definition_path.parent
+
+
+class AgentDefinitionStore:
+    """面向单机文件系统的 definition 存储。
+
+    当前实现很轻，只负责 YAML 读写；真正的校验交给 AgentDefinition。
+    """
+
+    def __init__(self, root: str | Path):
+        self.root = Path(root)
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    def definition_path(self, agent_id: str) -> Path:
+        return self.root / f"{agent_id}.yaml"
+
+    def list_paths(self) -> list[Path]:
+        return sorted(self.root.glob("*.yaml"))
+
+    def list_definitions(self) -> list[AgentDefinition]:
+        return [self.load_path(path) for path in self.list_paths()]
+
+    def load(self, agent_id: str) -> AgentDefinition:
+        return self.load_path(self.definition_path(agent_id))
+
+    def load_path(self, path: str | Path) -> AgentDefinition:
+        # 读取后先做环境变量替换，再交给 pydantic 做结构校验。
+        resolved_path = Path(path).resolve()
+        logger.debug("Loading agent definition path=%s", resolved_path)
+        try:
+            with resolved_path.open("r", encoding="utf-8") as handle:
+                raw = yaml.safe_load(handle) or {}
+        except FileNotFoundError as exc:
+            logger.exception("Definition file not found path=%s", resolved_path)
+            raise DefinitionLoadError(
+                f"definition file not found: '{resolved_path}'",
+                user_message="Agent 配置文件不存在，请检查 agent_app/agent.yaml 路径",
+            ) from exc
+        except yaml.YAMLError as exc:
+            logger.exception("Invalid YAML in definition path=%s", resolved_path)
+            raise DefinitionLoadError(
+                f"invalid YAML in definition file '{resolved_path}': {exc}",
+                user_message="Agent 配置文件格式错误，请检查 YAML 语法",
+            ) from exc
+
+        try:
+            resolved_raw = _resolve_env_placeholders(raw)
+            runtime_raw = resolved_raw.get("runtime")
+            if not isinstance(runtime_raw, dict):
+                runtime_raw = {}
+            raw_base_path = runtime_raw.get("base_path", ".")
+            base_path = Path(raw_base_path)
+            if not base_path.is_absolute():
+                base_path = (_default_base_root(resolved_path) / base_path).resolve()
+            resolved_raw["runtime"] = {**runtime_raw, "base_path": base_path.as_posix()}
+            definition = AgentDefinition.model_validate(resolved_raw)
+            logger.debug("Loaded agent definition agent_id=%s path=%s", definition.agent.agent_id, resolved_path)
+            return definition
+        except Exception as exc:
+            logger.exception("Failed to validate definition path=%s", resolved_path)
+            raise DefinitionLoadError(
+                f"failed to validate definition file '{resolved_path}': {exc}",
+                user_message="Agent 配置校验失败，请检查 agent_app/agent.yaml 必填项和字段格式",
+            ) from exc
+
+    def save(self, definition: AgentDefinition) -> Path:
+        path = self.definition_path(definition.agent.agent_id)
+        with path.open("w", encoding="utf-8") as handle:
+            yaml.safe_dump(definition.model_dump(mode="python"), handle, allow_unicode=True, sort_keys=False)
+        return path
+
+    def delete(self, agent_id: str) -> None:
+        path = self.definition_path(agent_id)
+        if path.exists():
+            path.unlink()

agent_runtime/context.py

@@ -0,0 +1,10 @@
+"""对外暴露的运行时任务上下文入口。"""
+
+from .runtime_engine.context import (
+    TaskContext,
+    TaskPool,
+    current_task_id,
+    current_task_pool,
+)
+
+__all__ = ["TaskContext", "TaskPool", "current_task_id", "current_task_pool"]

agent_runtime/definitions.py

@@ -0,0 +1,33 @@
+"""Public facade for configuration models."""
+
+from .config.definitions import (
+    DEFAULT_PASS_THROUGH_HEADERS,
+    DEFAULT_PLUGIN_CLASS_NAME,
+    DEFAULT_PLUGIN_MODULE_PATH,
+    A2ASettings,
+    AgentConfig,
+    AgentDefinition,
+    InputFieldDefinition,
+    MCPSettings,
+    ModelSettings,
+    PluginSettings,
+    RuntimeConfig,
+    SkillDefinition,
+    ToolPolicy,
+)
+
+__all__ = [
+    "DEFAULT_PASS_THROUGH_HEADERS",
+    "DEFAULT_PLUGIN_CLASS_NAME",
+    "DEFAULT_PLUGIN_MODULE_PATH",
+    "A2ASettings",
+    "AgentConfig",
+    "AgentDefinition",
+    "InputFieldDefinition",
+    "MCPSettings",
+    "ModelSettings",
+    "PluginSettings",
+    "RuntimeConfig",
+    "SkillDefinition",
+    "ToolPolicy",
+]

agent_runtime/discovery.py

@@ -0,0 +1,16 @@
+"""对外暴露的 MCP discovery 辅助入口。"""
+
+from .mcp.discovery import (
+    default_discover_tools,
+    load_mcp_client_and_tools,
+    load_mcp_tools,
+)
+from .mcp.metadata import DiscoveredTool, discovered_tool_from_tool
+
+__all__ = [
+    "DiscoveredTool",
+    "default_discover_tools",
+    "discovered_tool_from_tool",
+    "load_mcp_client_and_tools",
+    "load_mcp_tools",
+]

agent_runtime/exceptions.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+"""框架统一异常类型。
+
+原则：
+- 日志里保留内部真实异常
+- 对用户返回稳定、可预期的文案
+- 启动期和请求期都尽量用语义明确的异常类型，而不是到处混用 RuntimeError
+"""
+
+
+class AgentRuntimeError(Exception):
+    """框架异常基类，附带稳定的用户可见文案。"""
+
+    default_user_message = "任务执行失败，请稍后重试"
+    default_code = "agent_runtime_error"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        user_message: str | None = None,
+        code: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.user_message = user_message or self.default_user_message
+        self.code = code or self.default_code
+
+
+class DefinitionLoadError(AgentRuntimeError):
+    default_user_message = "Agent 配置加载失败，请检查 agent_app/agent.yaml"
+    default_code = "definition_load_error"
+
+
+class PluginLoadError(AgentRuntimeError):
+    default_user_message = "Agent 插件加载失败，请检查 plugin 配置"
+    default_code = "plugin_load_error"
+
+
+class MCPToolLoadError(AgentRuntimeError):
+    default_user_message = "MCP 工具加载失败，请检查 MCP 服务和网络连通性"
+    default_code = "mcp_tool_load_error"
+
+
+class AgentBuildError(AgentRuntimeError):
+    default_user_message = "Agent 构建失败，请检查模型、插件和工具配置"
+    default_code = "agent_build_error"
+
+
+class TaskWaitTimeoutError(AgentRuntimeError):
+    default_user_message = "任务等待超时，已自动结束"
+    default_code = "task_wait_timeout"
+
+
+class TaskExecutionTimeoutError(AgentRuntimeError):
+    default_user_message = "任务执行超时，已自动取消"
+    default_code = "task_execution_timeout"
+
+
+class UserCancelledError(AgentRuntimeError):
+    default_user_message = "用户已取消操作"
+    default_code = "user_cancelled"
+
+
+class TaskCancelledError(AgentRuntimeError):
+    default_user_message = "任务已取消"
+    default_code = "task_cancelled"
+
+
+def user_message_for_error(error: Exception) -> str:
+    """把内部异常映射成稳定的用户可见文案。"""
+    if isinstance(error, AgentRuntimeError):
+        return error.user_message
+    return AgentRuntimeError.default_user_message

agent_runtime/mcp/__init__.py

@@ -0,0 +1,28 @@
+"""MCP 相关内部实现。
+
+模块划分：
+
+- `metadata.py`: 工具描述对象与规整逻辑
+- `utils.py`: MCP 共用规则
+- `discovery.py`: discover/load 主流程
+"""
+
+from .discovery import default_discover_tools, load_mcp_client_and_tools, load_mcp_tools
+from .metadata import (
+    DiscoveredTool,
+    discovered_tool_from_tool,
+    normalize_discovered_tools,
+)
+from .utils import index_tool_sources, merge_mcp_headers, register_tool_source
+
+__all__ = [
+    "DiscoveredTool",
+    "default_discover_tools",
+    "discovered_tool_from_tool",
+    "index_tool_sources",
+    "load_mcp_client_and_tools",
+    "load_mcp_tools",
+    "merge_mcp_headers",
+    "normalize_discovered_tools",
+    "register_tool_source",
+]

agent_runtime/mcp/discovery.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+"""MCP 工具发现与加载。
+
+这个文件只保留 discover/load 主流程，不再承载 descriptor 模型和共用工具函数。
+
+这里区分两类动作：
+
+1. discover：只拿工具元数据，给管理面、prompt、agent card 使用
+2. load：真正创建 MCPClient，并返回可执行的 tool 对象
+"""
+
+import logging
+import time
+from typing import Any
+
+from ..config.definitions import MCPSettings
+from ..exceptions import MCPToolLoadError
+from .metadata import (
+    DiscoveredTool,
+    discovered_tool_from_tool,
+    normalize_discovered_tools,
+)
+from .utils import merge_mcp_headers
+
+logger = logging.getLogger(__name__)
+
+
+def default_discover_tools(
+    mcp: MCPSettings, headers: dict[str, str] | None = None
+) -> list[DiscoveredTool]:
+    """默认的工具发现流程。
+
+    这里只做“看工具”(list_tools) 拿工具 description ，因此 client 用完即关，不把连接留到运行时。
+    """
+    client, tools = load_mcp_client_and_tools(mcp, headers=headers)
+    try:
+        logger.debug(
+            "Discovered MCP tools mcp=%s url=%s tool_count=%s",
+            mcp.name,
+            mcp.url,
+            len(tools),
+        )
+        return normalize_discovered_tools(
+            (discovered_tool_from_tool(tool) for tool in tools), mcp.name
+        )
+    finally:
+        try:
+            client.disconnect()
+        except Exception:
+            logger.warning(
+                "Failed to disconnect discovery MCP client mcp=%s url=%s",
+                mcp.name,
+                mcp.url,
+                exc_info=True,
+            )
+
+
+def load_mcp_tools(
+    mcp: MCPSettings, headers: dict[str, str] | None = None
+) -> list[Any]:
+    """兼容旧用法：仅返回 tools，但把 client 挂到 tool 上，避免生命周期丢失。"""
+    client, tools = load_mcp_client_and_tools(mcp, headers=headers)
+    for tool in tools:
+        try:
+            tool._runtime_mcp_client = client
+        except Exception:
+            pass
+    return tools
+
+
+def load_mcp_client_and_tools(
+    mcp: MCPSettings, headers: dict[str, str] | None = None
+) -> tuple[Any, list[Any]]:
+    """创建一个 MCPClient，并把这个 MCP 暴露的工具全部取出来。
+
+    这里是运行时真正执行工具前的入口，所以失败时要负责把刚创建的 client 清干净。
+    """
+    from smolagents import MCPClient
+
+    merged_headers = merge_mcp_headers(mcp, headers)
+    total_attempts = mcp.retry_count + 1
+    last_exc: Exception | None = None
+
+    for attempt in range(1, total_attempts + 1):
+        client = None
+        try:
+            client = MCPClient(
+                {"url": mcp.url, "transport": mcp.transport, "headers": merged_headers},
+                structured_output=False,
+            )
+            tools = client.get_tools()
+            logger.debug(
+                "Loaded MCP client and tools mcp=%s url=%s tool_count=%s attempt=%s/%s",
+                mcp.name,
+                mcp.url,
+                len(tools),
+                attempt,
+                total_attempts,
+            )
+            return client, tools
+        except Exception as exc:
+            last_exc = exc
+            logger.exception(
+                "Failed to create/load MCP client mcp=%s url=%s attempt=%s/%s",
+                mcp.name,
+                mcp.url,
+                attempt,
+                total_attempts,
+            )
+            if client is not None:
+                try:
+                    client.disconnect()
+                except Exception:
+                    logger.warning(
+                        "Failed to disconnect MCP client after tool load failure mcp=%s url=%s attempt=%s/%s",
+                        mcp.name,
+                        mcp.url,
+                        attempt,
+                        total_attempts,
+                        exc_info=True,
+                    )
+
+            if attempt < total_attempts:
+                logger.warning(
+                    "Retrying MCP client load mcp=%s url=%s in %ss after failure (%s/%s)",
+                    mcp.name,
+                    mcp.url,
+                    mcp.retry_delay_seconds,
+                    attempt,
+                    total_attempts,
+                )
+                if mcp.retry_delay_seconds > 0:
+                    time.sleep(mcp.retry_delay_seconds)
+
+    retry_note = f"after {total_attempts} attempts ({mcp.retry_count} retries)"
+    raise MCPToolLoadError(
+        (
+            f"failed to create/load MCP client for mcp '{mcp.name}' at '{mcp.url}' "
+            f"{retry_note}: {last_exc}"
+        ),
+        user_message=(
+            f"MCP 服务 '{mcp.name}' 连接失败，已重试 {mcp.retry_count} 次后仍不可用，"
+            "请检查服务状态和网络连通性"
+        ),
+    ) from last_exc

agent_runtime/mcp/metadata.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+"""MCP 工具元数据模型。
+
+这个文件只处理“工具长什么样”：
+
+- `DiscoveredTool`: discovery 阶段的只读工具摘要
+- `discovered_tool_from_tool`: 把具体 tool 对象压平为摘要
+- `normalize_discovered_tools`: 规整 discoverer 返回值，并补齐 `source_mcp`
+
+注意：
+
+- 这里的对象不是原生 MCP 可执行 tool
+- 它只服务于管理面、prompt 展示、工具列表和策略定位
+- 真正执行工具时，runtime 仍然使用原生 tool 对象
+"""
+
+from typing import Any, Iterable
+
+from pydantic import BaseModel, Field
+
+
+class DiscoveredTool(BaseModel):
+    """discovery 阶段的只读工具摘要。
+
+    之所以不直接缓存原生 MCP tool，是因为 discovery 阶段只需要稳定、可序列化、
+    可长期持有的元数据；真正执行工具时，会重新拿原生 tool 实例。
+    """
+
+    name: str
+    source_mcp: str | None = None
+    description: str = ""
+    inputs: dict[str, Any] = Field(default_factory=dict)
+    output_type: str | None = None
+
+
+def discovered_tool_from_tool(
+    tool: Any, source_mcp: str | None = None
+) -> DiscoveredTool:
+    """把具体 tool 对象压平成稳定的 discovered tool 摘要。"""
+
+    return DiscoveredTool(
+        name=getattr(tool, "name", ""),
+        source_mcp=source_mcp,
+        description=getattr(tool, "description", "") or "",
+        inputs=getattr(tool, "inputs", {}) or {},
+        output_type=getattr(tool, "output_type", None),
+    )
+
+
+def normalize_discovered_tools(
+    items: Iterable[Any], source_mcp: str
+) -> list[DiscoveredTool]:
+    """把 discoverer 返回值统一规整成带 `source_mcp` 的 discovered tools。"""
+
+    discovered_tools: list[DiscoveredTool] = []
+    for item in items:
+        discovered_tool = (
+            item
+            if isinstance(item, DiscoveredTool)
+            else DiscoveredTool.model_validate(item)
+        )
+        discovered_tools.append(
+            discovered_tool.model_copy(
+                update={"source_mcp": discovered_tool.source_mcp or source_mcp}
+            )
+        )
+    return discovered_tools

agent_runtime/mcp/utils.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+"""MCP 共用工具函数。
+
+这个文件只放多处复用的 MCP 规则：
+
+- header 合并
+- tool source 建索引
+- 重名工具冲突检测
+"""
+
+from collections.abc import Iterable
+
+from ..config.definitions import MCPSettings
+from .metadata import DiscoveredTool
+
+
+def merge_mcp_headers(
+    mcp: MCPSettings, headers: dict[str, str] | None = None
+) -> dict[str, str]:
+    """合并 MCP 静态头和调用期透传头。"""
+
+    merged_headers = dict(mcp.static_headers)
+    if headers:
+        merged_headers.update({key: value for key, value in headers.items() if value})
+    return merged_headers
+
+
+def register_tool_source(
+    tool_sources: dict[str, str], tool_name: str, source_mcp: str
+) -> None:
+    """记录工具来源，并在同名冲突时抛出一致错误。"""
+
+    existing_source = tool_sources.get(tool_name)
+    if existing_source is not None:
+        raise ValueError(
+            f"duplicate MCP tool name '{tool_name}' from '{existing_source}' and '{source_mcp}'"
+        )
+    tool_sources[tool_name] = source_mcp
+
+
+def index_tool_sources(discovered_tools: Iterable[DiscoveredTool]) -> dict[str, str]:
+    """为已发现工具建立 `name -> source_mcp` 索引。"""
+
+    tool_sources: dict[str, str] = {}
+    for discovered_tool in discovered_tools:
+        register_tool_source(
+            tool_sources,
+            discovered_tool.name,
+            discovered_tool.source_mcp or "",
+        )
+    return tool_sources

agent_runtime/model_registry.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class ModelRegistry:
+    """Pluggable LLM model factory.
+
+    Register model classes by provider name and create instances via
+    ``ModelRegistry.create(provider, **kwargs)``.
+    """
+
+    _providers: dict[str, type] = {}
+
+    @classmethod
+    def register(cls, name: str, model_cls: type) -> None:
+        cls._providers[name] = model_cls
+
+    @classmethod
+    def create(cls, provider: str, **kwargs: Any):
+        model_cls = cls._providers.get(provider)
+        if model_cls is None:
+            raise ValueError(
+                f"Unknown model provider: {provider}. "
+                f"Registered: {list(cls._providers.keys())}"
+            )
+        return model_cls(**kwargs)
+
+    @classmethod
+    def list_providers(cls) -> list[str]:
+        return list(cls._providers.keys())
+
+
+def _register_defaults() -> None:
+    from .smol import DeepSeekModel
+
+    ModelRegistry.register("openai_compatible", DeepSeekModel)
+
+
+_register_defaults()

agent_runtime/plugins/__init__.py

@@ -0,0 +1,4 @@
+from .base import BaseAgentPlugin, BeforeToolDecision, ToolExecutionContext
+from .loader import load_plugin
+
+__all__ = ["BaseAgentPlugin", "BeforeToolDecision", "ToolExecutionContext", "load_plugin"]

agent_runtime/plugins/base.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+"""插件扩展点定义。
+
+框架把“工具如何调用、提示词如何生成、结果如何格式化”这些可变逻辑
+都收敛到 plugin 接口里，避免把业务定制写死在 runtime 中。
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+from ..config.definitions import AgentDefinition, InputFieldDefinition
+
+
+@dataclass
+class BeforeToolDecision:
+    """插件在工具执行前给出的治理决策。"""
+
+    requires_confirmation: bool | None = None
+    input_fields: list[InputFieldDefinition] = field(default_factory=list)
+    prompt: str | None = None
+    allow_arg_override: bool | None = None
+
+
+@dataclass
+class ToolExecutionContext:
+    """传给 plugin 的统一上下文。
+
+    这里尽量把 plugin 关心的信息收全：当前 agent 定义、工具名、参数、
+    来源 MCP、原始 tool_call、执行结果等。
+    """
+
+    agent_definition: AgentDefinition
+    tool_name: str
+    args: dict[str, Any]
+    mcp_name: str | None = None
+    task_info: Any = None
+    raw_tool_call: Any = None
+    observation: Any = None
+    result: Any = None
+
+
+class AgentPlugin(Protocol):
+    """插件协议：描述一个 plugin 至少要提供哪些扩展点。"""
+
+    def build_instructions(self, definition: AgentDefinition, tools: list[Any]) -> str:
+        ...
+
+    def extra_tools(self, definition: AgentDefinition) -> list[Any]:
+        ...
+
+    def before_tool(self, context: ToolExecutionContext) -> BeforeToolDecision | None:
+        ...
+
+    def normalize_args(self, context: ToolExecutionContext) -> dict[str, Any] | None:
+        ...
+
+    def after_tool(self, context: ToolExecutionContext) -> None:
+        ...
+
+    def format_result(self, context: ToolExecutionContext) -> str | dict[str, Any] | None:
+        ...
+
+
+class BaseAgentPlugin:
+    """插件基类。
+
+    所有扩展点默认都是 no-op，这样业务插件只需要覆盖自己关心的那几项。
+    """
+
+    def __init__(self, config: dict[str, Any] | None = None):
+        self.config = config or {}
+
+    def build_instructions(self, definition: AgentDefinition, tools: list[Any]) -> str:
+        return ""
+
+    def extra_tools(self, definition: AgentDefinition) -> list[Any]:
+        return []
+
+    def before_tool(self, context: ToolExecutionContext) -> BeforeToolDecision | None:
+        return None
+
+    def normalize_args(self, context: ToolExecutionContext) -> dict[str, Any] | None:
+        return None
+
+    def after_tool(self, context: ToolExecutionContext) -> None:
+        return None
+
+    def format_result(self, context: ToolExecutionContext) -> str | dict[str, Any] | None:
+        return None