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

agent_runtime/sdk_agent.py

@@ -0,0 +1,548 @@
+from __future__ import annotations
+
+"""面向 SDK 使用者的类式 agent 抽象。
+
+设计目标：
+
+1. YAML 配置方式和 Python 类方式都收敛到同一个规范层：`AgentDefinition`
+2. 业务方既可以直接声明完整 definition，也可以只覆写少量小钩子
+3. 基类数量不追求多，而是提供少量高价值的“半成品基类”
+
+建议分层：
+
+- `BaseSDKAgent`: 只管 definition / builder / runtime / app 生命周期
+- `DeclarativeSDKAgent`: 适合直接返回完整 definition 的场景
+- `ConfiguredSDKAgent`: 适合用细粒度 hook 组装 definition
+- `SingleMCPAgent`: 单 MCP 场景的高频半成品
+- `OpenAICompatibleSingleMCPAgent`: 单 MCP + OpenAI-compatible 模型的常见半成品
+"""
+
+import os
+from abc import ABC, abstractmethod
+from typing import Any, Callable
+
+from .builder import AgentBuilder
+from .config.definitions import (
+    DEFAULT_PASS_THROUGH_HEADERS,
+    A2ASettings,
+    AgentConfig,
+    AgentDefinition,
+    MCPSettings,
+    ModelSettings,
+    PluginSettings,
+    RuntimeConfig,
+    SkillDefinition,
+    ToolPolicy,
+)
+from .mcp.metadata import DiscoveredTool
+from .plugins.base import BaseAgentPlugin
+
+
+def _coerce_agent_config(value: AgentConfig | dict[str, Any]) -> AgentConfig:
+    return value if isinstance(value, AgentConfig) else AgentConfig.model_validate(value)
+
+
+def _coerce_runtime_config(
+    value: RuntimeConfig | dict[str, Any]
+) -> RuntimeConfig:
+    return (
+        value if isinstance(value, RuntimeConfig) else RuntimeConfig.model_validate(value)
+    )
+
+
+def _coerce_model_settings(
+    value: ModelSettings | dict[str, Any]
+) -> ModelSettings:
+    return value if isinstance(value, ModelSettings) else ModelSettings.model_validate(value)
+
+
+def _coerce_plugin_settings(
+    value: PluginSettings | dict[str, Any] | None,
+) -> PluginSettings | None:
+    if value is None or isinstance(value, PluginSettings):
+        return value
+    return PluginSettings.model_validate(value)
+
+
+def _coerce_skill_definition(
+    value: SkillDefinition | dict[str, Any]
+) -> SkillDefinition:
+    return (
+        value if isinstance(value, SkillDefinition) else SkillDefinition.model_validate(value)
+    )
+
+
+def _coerce_tool_policies(
+    policies: dict[str, ToolPolicy | dict[str, Any]] | None,
+) -> dict[str, ToolPolicy]:
+    resolved: dict[str, ToolPolicy] = {}
+    for tool_name, policy in (policies or {}).items():
+        resolved[tool_name] = (
+            policy if isinstance(policy, ToolPolicy) else ToolPolicy.model_validate(policy)
+        )
+    return resolved
+
+
+def _coerce_mcp_settings(
+    items: list[MCPSettings | dict[str, Any]]
+) -> list[MCPSettings]:
+    resolved: list[MCPSettings] = []
+    for item in items:
+        resolved.append(
+            item if isinstance(item, MCPSettings) else MCPSettings.model_validate(item)
+        )
+    return resolved
+
+
+def _resolve_string_setting(
+    *,
+    explicit: str | None,
+    env_var: str | None = None,
+    default: str | None = None,
+) -> str | None:
+    """统一处理“显式值 -> 环境变量 -> 默认值”的解析顺序。"""
+
+    if explicit is not None:
+        return explicit
+    if env_var:
+        env_value = os.getenv(env_var)
+        if env_value:
+            return env_value
+    return default
+
+
+class BaseSDKAgent(ABC):
+    """类方式 agent 的最小生命周期基类。
+
+    这个类不关心业务字段长什么样，只约束一个核心事实：
+
+    - Python 类方式最终必须先收敛为 `AgentDefinition`
+
+    这样：
+    - YAML 入口和 Python 入口共用同一个 definition/spec 层
+    - `AgentBuilder.from_definition(...)` 成为统一装配路径
+    """
+
+    def definition(self) -> AgentDefinition:
+        """返回当前 agent 的规范化 definition。
+
+        这里把 `build_definition()` 的结果统一转成 `AgentDefinition`，
+        并给子类一个最终修改 definition 的扩展点。
+        """
+
+        raw = self.build_definition()
+        definition = (
+            raw if isinstance(raw, AgentDefinition) else AgentDefinition.model_validate(raw)
+        )
+        # 统一用深拷贝，避免子类返回共享对象后被后续调用原地改坏。
+        definition = definition.model_copy(deep=True)
+        customized = self.customize_definition(definition)
+        return definition if customized is None else customized
+
+    @abstractmethod
+    def build_definition(self) -> AgentDefinition | dict[str, Any]:
+        """构造当前 agent 的 definition/spec。"""
+
+    def builder(self) -> AgentBuilder:
+        """把当前类式 agent 转成 `AgentBuilder`。
+
+        这个方法是类方式和 builder 方式之间的桥接点。
+        """
+
+        builder = AgentBuilder.from_definition(self.definition())
+
+        explicit_model_api_key = self.model_api_key()
+        if explicit_model_api_key is not None:
+            builder.model(api_key=explicit_model_api_key)
+
+        discoverer = self.discoverer()
+        if discoverer is not None:
+            builder.discoverer(discoverer)
+
+        plugin = self.plugin_instance()
+        if plugin is not None:
+            builder.plugin(plugin)
+
+        self.customize_builder(builder)
+        return builder
+
+    def build_runtime(self):
+        """构造并返回 `ManagedAgentRuntime`。"""
+
+        return self.builder().build()
+
+    def build_app(
+        self,
+        *,
+        enable_management: bool = False,
+        public_url: str | None = None,
+    ):
+        """构造并返回可直接挂到 uvicorn 的 A2A app。"""
+
+        return self.builder().build_a2a_app(
+            public_url=public_url,
+            enable_management=enable_management,
+        )
+
+    def model_api_key(self) -> str | None:
+        """可选：返回只存在于运行时的显式 API Key。
+
+        之所以不放进 `AgentDefinition`，是因为 definition 适合作为配置规格，
+        而不是密钥载体。
+        """
+
+        return None
+
+    def plugin_instance(self) -> BaseAgentPlugin | None:
+        """可选：返回业务 plugin 实例。
+
+        如果这里返回实例，会覆盖 definition 里的 `runtime.plugin` 加载路径。
+        """
+
+        return None
+
+    def discoverer(self) -> Callable[..., list[DiscoveredTool]] | None:
+        """可选：返回自定义 MCP discoverer。"""
+
+        return None
+
+    def customize_definition(
+        self, definition: AgentDefinition
+    ) -> AgentDefinition | None:
+        """可选：在 definition 完成后做最后修正。"""
+
+        return definition
+
+    def customize_builder(self, builder: AgentBuilder) -> None:
+        """可选：在 builder 完成后做最后修正。"""
+
+        return None
+
+
+class DeclarativeSDKAgent(BaseSDKAgent):
+    """适合“我已经有完整 definition，只想走类入口”的场景。"""
+
+    @abstractmethod
+    def declared_definition(self) -> AgentDefinition | dict[str, Any]:
+        """返回完整 definition。"""
+
+    def build_definition(self) -> AgentDefinition | dict[str, Any]:
+        return self.declared_definition()
+
+
+class ConfiguredSDKAgent(BaseSDKAgent):
+    """适合通过细粒度 hook 组装 definition 的通用基类。
+
+    这层的重点不是“业务一定要全部重写”，而是把常见变更点拆小：
+
+    - 身份信息拆成 `agent_id/name/description/version`
+    - 模型拆成 provider/base/model_id/api_key_env/max_steps
+    - A2A 展示层拆成 skills 和输入输出模式
+    - MCP 拆成一个或多个 `MCPSettings`
+    """
+
+    def build_definition(self) -> AgentDefinition:
+        return AgentDefinition(
+            agent=_coerce_agent_config(self.agent_config()),
+            runtime=_coerce_runtime_config(self.runtime_config()),
+            mcps=_coerce_mcp_settings(self.mcp_settings()),
+        )
+
+    def agent_config(self) -> AgentConfig | dict[str, Any]:
+        return AgentConfig(
+            agent_id=self.agent_id(),
+            name=self.agent_name(),
+            description=self.agent_description(),
+            version=self.agent_version(),
+            a2a=self.a2a_settings(),
+            extra_instructions=self.extra_instructions(),
+        )
+
+    def runtime_config(self) -> RuntimeConfig | dict[str, Any]:
+        return RuntimeConfig(
+            base_path=self.base_path(),
+            public_base_url=self.public_base_url(),
+            model=_coerce_model_settings(self.model_settings()),
+            plugin=_coerce_plugin_settings(self.plugin_settings()),
+        )
+
+    def model_settings(self) -> ModelSettings | dict[str, Any]:
+        return ModelSettings(
+            provider=self.model_provider(),
+            api_base=self.model_api_base(),
+            model_id=self.model_id(),
+            api_key_env=self.model_api_key_env(),
+            max_steps=self.model_max_steps(),
+            flatten_messages_as_text=self.model_flatten_messages_as_text(),
+        )
+
+    def a2a_settings(self) -> A2ASettings:
+        return A2ASettings(
+            skills=[_coerce_skill_definition(skill) for skill in self.a2a_skills()],
+            default_input_modes=list(self.a2a_default_input_modes()),
+            default_output_modes=list(self.a2a_default_output_modes()),
+        )
+
+    @abstractmethod
+    def agent_id(self) -> str:
+        """返回稳定的内部 agent 标识。"""
+
+    def agent_name(self) -> str:
+        """返回展示名称。
+
+        默认回退到 `agent_id()`，让最小子类只实现一个必填钩子也能工作。
+        """
+
+        return self.agent_id()
+
+    def agent_description(self) -> str:
+        """返回展示描述。默认回退到 `agent_name()`。"""
+
+        return self.agent_name()
+
+    def agent_version(self) -> str:
+        return "0.1.0"
+
+    def extra_instructions(self) -> str:
+        return ""
+
+    def a2a_skills(self) -> list[SkillDefinition | dict[str, Any]]:
+        return []
+
+    def a2a_default_input_modes(self) -> list[str]:
+        return ["text"]
+
+    def a2a_default_output_modes(self) -> list[str]:
+        return ["text"]
+
+    def base_path(self) -> str:
+        return "."
+
+    def public_base_url(self) -> str | None:
+        return None
+
+    def model_provider(self) -> str:
+        return "openai_compatible"
+
+    def model_api_base(self) -> str | None:
+        return None
+
+    def model_id(self) -> str | None:
+        return None
+
+    def model_api_key_env(self) -> str:
+        return "MODEL_SOURCE_API_KEY"
+
+    def model_max_steps(self) -> int:
+        return 15
+
+    def model_flatten_messages_as_text(self) -> bool:
+        return True
+
+    def plugin_settings(self) -> PluginSettings | dict[str, Any] | None:
+        return None
+
+    @abstractmethod
+    def mcp_settings(self) -> list[MCPSettings | dict[str, Any]]:
+        """返回一个或多个 MCP 绑定。"""
+
+
+class SingleMCPAgent(ConfiguredSDKAgent):
+    """单 MCP 场景的半成品基类。"""
+
+    def mcp_settings(self) -> list[MCPSettings]:
+        return [
+            MCPSettings(
+                name=self.mcp_name(),
+                url=self.mcp_url(),
+                transport=self.mcp_transport(),
+                enabled=self.mcp_enabled(),
+                retry_count=self.mcp_retry_count(),
+                retry_delay_seconds=self.mcp_retry_delay_seconds(),
+                static_headers=dict(self.mcp_static_headers()),
+                pass_through_headers=list(self.mcp_pass_through_headers()),
+                tool_policies=_coerce_tool_policies(self.mcp_tool_policies()),
+            )
+        ]
+
+    @abstractmethod
+    def mcp_name(self) -> str:
+        """返回单个 MCP 的名称。"""
+
+    @abstractmethod
+    def mcp_url(self) -> str:
+        """返回单个 MCP 的地址。"""
+
+    def mcp_transport(self) -> str:
+        return "streamable-http"
+
+    def mcp_enabled(self) -> bool:
+        return True
+
+    def mcp_retry_count(self) -> int:
+        return 3
+
+    def mcp_retry_delay_seconds(self) -> float:
+        return 1.0
+
+    def mcp_static_headers(self) -> dict[str, str]:
+        return {}
+
+    def mcp_pass_through_headers(self) -> list[str]:
+        return list(DEFAULT_PASS_THROUGH_HEADERS)
+
+    def mcp_tool_policies(self) -> dict[str, ToolPolicy | dict[str, Any]]:
+        return {}
+
+
+class OpenAICompatibleSingleMCPAgent(SingleMCPAgent):
+    """单 MCP + OpenAI-compatible 模型的常用半成品基类。
+
+    这个类面向业务开发者的目标是：
+
+    - 不用关心 `AgentBuilder` 细节
+    - 常见配置支持“显式参数 -> 环境变量 -> 默认值”三级覆盖
+    - 只需要覆写少量语义化小钩子
+    """
+
+    def __init__(
+        self,
+        *,
+        public_base_url: str | None = None,
+        model_api_base: str | None = None,
+        model_id: str | None = None,
+        model_api_key: str | None = None,
+        mcp_url: str | None = None,
+        mcp_transport: str | None = None,
+        mcp_retry_count: int | None = None,
+        mcp_retry_delay_seconds: float | None = None,
+        max_steps: int | None = None,
+        flatten_messages_as_text: bool | None = None,
+    ) -> None:
+        self._public_base_url_override = public_base_url
+        self._model_api_base_override = model_api_base
+        self._model_id_override = model_id
+        self._model_api_key_override = model_api_key
+        self._mcp_url_override = mcp_url
+        self._mcp_transport_override = mcp_transport
+        self._mcp_retry_count_override = mcp_retry_count
+        self._mcp_retry_delay_seconds_override = mcp_retry_delay_seconds
+        self._model_max_steps_override = max_steps
+        self._flatten_messages_as_text_override = flatten_messages_as_text
+
+    def public_base_url(self) -> str | None:
+        return _resolve_string_setting(
+            explicit=self._public_base_url_override,
+            env_var=self.public_base_url_env_var(),
+            default=self.default_public_base_url(),
+        )
+
+    def model_provider(self) -> str:
+        return "openai_compatible"
+
+    def model_api_base(self) -> str | None:
+        return _resolve_string_setting(
+            explicit=self._model_api_base_override,
+            env_var=self.model_api_base_env_var(),
+            default=self.default_model_api_base(),
+        )
+
+    def model_id(self) -> str | None:
+        return _resolve_string_setting(
+            explicit=self._model_id_override,
+            env_var=self.model_id_env_var(),
+            default=self.default_model_id(),
+        )
+
+    def model_api_key(self) -> str | None:
+        # 这里有意只返回显式传入的 key。
+        #
+        # 正常情况下，SDK 仍建议通过 `model_api_key_env()` 指定环境变量读取。
+        # 只有业务方明确想在代码里塞一个临时 key 时，才走这个运行时 override。
+        return self._model_api_key_override
+
+    def model_max_steps(self) -> int:
+        if self._model_max_steps_override is not None:
+            return self._model_max_steps_override
+        return self.default_model_max_steps()
+
+    def model_flatten_messages_as_text(self) -> bool:
+        if self._flatten_messages_as_text_override is not None:
+            return self._flatten_messages_as_text_override
+        return self.default_model_flatten_messages_as_text()
+
+    def mcp_url(self) -> str:
+        value = _resolve_string_setting(
+            explicit=self._mcp_url_override,
+            env_var=self.mcp_url_env_var(),
+            default=self.default_mcp_url(),
+        )
+        if not value:
+            raise ValueError(
+                "mcp_url is not configured; pass mcp_url=..., "
+                f"set env {self.mcp_url_env_var()!r}, or override default_mcp_url()."
+            )
+        return value
+
+    def mcp_transport(self) -> str:
+        value = _resolve_string_setting(
+            explicit=self._mcp_transport_override,
+            env_var=self.mcp_transport_env_var(),
+            default=self.default_mcp_transport(),
+        )
+        return value or "streamable-http"
+
+    def mcp_retry_count(self) -> int:
+        if self._mcp_retry_count_override is not None:
+            return self._mcp_retry_count_override
+        return self.default_mcp_retry_count()
+
+    def mcp_retry_delay_seconds(self) -> float:
+        if self._mcp_retry_delay_seconds_override is not None:
+            return self._mcp_retry_delay_seconds_override
+        return self.default_mcp_retry_delay_seconds()
+
+    def public_base_url_env_var(self) -> str | None:
+        return "AGENT_PUBLIC_BASE_URL"
+
+    def default_public_base_url(self) -> str | None:
+        return None
+
+    def model_api_base_env_var(self) -> str | None:
+        return "MODEL_SOURCE_API_BASE"
+
+    def default_model_api_base(self) -> str | None:
+        return None
+
+    def model_id_env_var(self) -> str | None:
+        return "MODEL_SOURCE_MODEL_ID"
+
+    def default_model_id(self) -> str | None:
+        return None
+
+    def model_api_key_env(self) -> str:
+        return "MODEL_SOURCE_API_KEY"
+
+    def default_model_max_steps(self) -> int:
+        return 15
+
+    def default_model_flatten_messages_as_text(self) -> bool:
+        return True
+
+    def mcp_url_env_var(self) -> str | None:
+        return None
+
+    def default_mcp_url(self) -> str | None:
+        return None
+
+    def mcp_transport_env_var(self) -> str | None:
+        return None
+
+    def default_mcp_transport(self) -> str | None:
+        return "streamable-http"
+
+    def default_mcp_retry_count(self) -> int:
+        return 3
+
+    def default_mcp_retry_delay_seconds(self) -> float:
+        return 1.0

agent_runtime/server/__init__.py

@@ -0,0 +1,15 @@
+"""服务装配层内部实现。"""
+
+from .app_factory import build_app_from_runtime
+from .bootstrap import DEFAULT_DEFINITION_PATH, load_single_agent_runtime
+from .endpoint_utils import port_from_public_base_url, resolve_public_base_url
+from .management import create_management_router
+
+__all__ = [
+    "DEFAULT_DEFINITION_PATH",
+    "build_app_from_runtime",
+    "create_management_router",
+    "load_single_agent_runtime",
+    "port_from_public_base_url",
+    "resolve_public_base_url",
+]

agent_runtime/server/app_factory.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+from ..runtime import ManagedAgentRuntime
+
+
+def build_app_from_runtime(
+    runtime: ManagedAgentRuntime,
+    enable_management: bool = True,
+) -> FastAPI:
+    """把已经构造好的 runtime 包成 FastAPI 应用。"""
+
+    if runtime.load_error:
+        if runtime.load_exception is not None:
+            raise runtime.load_exception
+        raise RuntimeError(runtime.load_error)
+
+    app = FastAPI(title=runtime.definition.agent.name)
+    app.state.runtime = runtime
+
+    @app.get("/healthz")
+    def healthz():
+        return {
+            "status": runtime.status,
+            "agent_id": runtime.definition.agent.agent_id,
+            "tool_count": len(runtime.discovered_tools),
+            "load_error": runtime.load_error,
+        }
+
+    if enable_management:
+        from .management import create_management_router
+
+        app.include_router(create_management_router(runtime))
+
+    app.mount("/", runtime.get_asgi_app())
+    return app

agent_runtime/server/bootstrap.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from .endpoint_utils import resolve_public_base_url
+from ..config.storage import AgentDefinitionStore
+from ..runtime import ManagedAgentRuntime
+
+
+DEFAULT_DEFINITION_PATH = Path.cwd() / "agent_app" / "agent.yaml"
+logger = logging.getLogger(__name__)
+
+
+def load_single_agent_runtime(
+    definition_path: str | Path = DEFAULT_DEFINITION_PATH,
+    public_base_url: str | None = None,
+    bind_port: int | None = None,
+    discoverer=None,
+) -> ManagedAgentRuntime:
+    """加载一个 definition，并立即完成 runtime reload。"""
+
+    logger.info("Loading single-agent runtime definition_path=%s", definition_path)
+    definition = AgentDefinitionStore(Path(definition_path).resolve().parent).load_path(definition_path)
+    resolved_public_base_url = resolve_public_base_url(
+        definition,
+        public_base_url=public_base_url,
+        bind_port=bind_port,
+    )
+    runtime = ManagedAgentRuntime(
+        definition=definition,
+        public_base_url=resolved_public_base_url,
+        discoverer=discoverer,
+    ).reload()
+    if runtime.load_error:
+        logger.error(
+            "Runtime loaded with error agent_id=%s load_error=%s",
+            runtime.definition.agent.agent_id,
+            runtime.load_error,
+        )
+    else:
+        logger.info(
+            "Runtime ready agent_id=%s public_base_url=%s discovered_tools=%s",
+            runtime.definition.agent.agent_id,
+            runtime.public_url(),
+            len(runtime.discovered_tools),
+        )
+    return runtime

agent_runtime/server/endpoint_utils.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+from ..config.definitions import AgentDefinition
+
+
+def port_from_public_base_url(public_base_url: str | None) -> int | None:
+    """从 public_base_url 中提取显式端口。"""
+
+    normalized = (public_base_url or "").rstrip("/")
+    if not normalized:
+        return None
+    parsed = urlparse(normalized)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        return None
+    return parsed.port
+
+
+def resolve_public_base_url(
+    definition: AgentDefinition,
+    *,
+    public_base_url: str | None = None,
+    bind_port: int | None = None,
+    public_host: str = "127.0.0.1",
+) -> str:
+    """解析运行时最终使用的 public_base_url。"""
+
+    resolved_public_base_url = (public_base_url or definition.runtime.public_base_url or "").rstrip("/")
+    if resolved_public_base_url:
+        return resolved_public_base_url
+    if bind_port is not None and bind_port > 0:
+        return f"http://{public_host}:{bind_port}"
+    raise ValueError(
+        "public_base_url must be configured in agent_app/agent.yaml or passed explicitly; "
+        "if you only want to bind a local port, pass bind_port/run_single_agent_app(..., port=...)."
+    )