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

agent_runtime/plugins/default.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .base import BaseAgentPlugin
+
+
+class DefaultPlugin(BaseAgentPlugin):
+    """默认兜底插件。
+
+    框架基础提示词会由 runtime 统一注入；DefaultPlugin 只补充配置里的额外说明。
+    """
+
+    def __init__(self, config: dict[str, Any] | None = None):
+        super().__init__(config)
+        self._extra_instructions: str = (config or {}).get("instructions", "")
+
+    def build_instructions(self, definition, tools: list) -> str:
+        return self._extra_instructions.strip()

agent_runtime/plugins/instructions.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def join_instruction_sections(*sections: str | None) -> str:
+    parts: list[str] = []
+    for section in sections:
+        if section is None:
+            continue
+        text = str(section).strip()
+        if text:
+            parts.append(text)
+    return "\n\n".join(parts)
+
+
+def build_framework_instructions(definition: Any, tools: list[Any]) -> str:
+    tool_lines: list[str] = []
+    for tool in tools:
+        line = f"- **{getattr(tool, 'name', '')}**"
+        description = getattr(tool, "description", "") or ""
+        if description:
+            line += f": {description}"
+        inputs = getattr(tool, "inputs", None) or {}
+        if inputs:
+            line += f"  (参数: {', '.join(inputs.keys())})"
+        tool_lines.append(line)
+
+    tool_section = "\n".join(tool_lines) if tool_lines else "(暂无工具)"
+    return (
+        f"你是 {definition.agent.name}，一个智能助手。\n\n"
+        f"## 可用工具\n{tool_section}\n\n"
+        "## 使用规则\n"
+        "- 需要补充信息时，调用 ask_user\n"
+        "- 需要用户授权确认时，调用 ask_auth\n"
+        "- 最终回答必须通过 final_answer 输出\n"
+        "- 不要猜测参数值，不确定就向用户确认\n"
+    )

agent_runtime/plugins/loader.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import logging
+import sys
+from pathlib import Path
+
+from .base import BaseAgentPlugin
+from ..exceptions import PluginLoadError
+
+logger = logging.getLogger(__name__)
+
+
+def _load_module(module_path: str):
+    if module_path.endswith(".py") or "/" in module_path:
+        path = Path(module_path).resolve()
+        module_name = f"dynamic_plugin_{path.stem}_{abs(hash(path))}"
+        spec = importlib.util.spec_from_file_location(module_name, path)
+        if spec is None or spec.loader is None:
+            raise ImportError(f"unable to load plugin module from {path}")
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[module_name] = module
+        spec.loader.exec_module(module)
+        return module
+
+    importlib.invalidate_caches()
+    return importlib.import_module(module_path)
+
+
+def load_plugin(module_path: str, class_name: str, config: dict | None = None) -> BaseAgentPlugin:
+    try:
+        module = _load_module(module_path)
+    except Exception as exc:
+        logger.exception("Failed to load plugin module path=%s", module_path)
+        raise PluginLoadError(
+            f"failed to load plugin module '{module_path}': {exc}",
+        ) from exc
+
+    try:
+        plugin_cls = getattr(module, class_name)
+    except AttributeError as exc:
+        logger.exception("Plugin class not found module=%s class=%s", module_path, class_name)
+        raise PluginLoadError(
+            f"plugin class '{class_name}' not found in '{module_path}'",
+        ) from exc
+
+    try:
+        plugin = plugin_cls(config=config or {})
+    except Exception as exc:
+        logger.exception("Failed to instantiate plugin module=%s class=%s", module_path, class_name)
+        raise PluginLoadError(
+            f"failed to instantiate plugin '{module_path}:{class_name}': {exc}",
+        ) from exc
+
+    if not isinstance(plugin, BaseAgentPlugin):
+        raise PluginLoadError(f"{module_path}:{class_name} must inherit BaseAgentPlugin")
+    logger.debug("Loaded plugin module=%s class=%s", module_path, class_name)
+    return plugin

agent_runtime/policies.py

@@ -0,0 +1,15 @@
+"""Public facade for tool-policy helper functions."""
+
+from .config.policies import (
+    collect_missing_fields,
+    is_missing,
+    merge_input_fields,
+    parse_user_payload,
+)
+
+__all__ = [
+    "collect_missing_fields",
+    "is_missing",
+    "merge_input_fields",
+    "parse_user_payload",
+]

agent_runtime/runtime.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+"""框架的运行时门面。
+
+这个文件只保留 runtime 的核心状态与 public API。
+具体实现按职责拆到 runtime_engine/：
+
+- loading.py: 插件加载与工具发现
+- agent_build.py: 单次请求的 agent 构建
+- tool_flow.py: 工具调用前的治理与中断
+- task_flow.py: 任务生命周期与等待恢复
+- a2a_bridge.py: A2A / ASGI 桥接
+"""
+
+from typing import Callable
+
+from .config.definitions import AgentDefinition, ToolPolicy
+from .mcp.discovery import default_discover_tools
+from .mcp.metadata import DiscoveredTool
+from .plugins import BaseAgentPlugin
+from .runtime_engine.context import TaskPool
+from .runtime_engine.a2a_bridge import RuntimeA2ABridge
+from .runtime_engine.agent_build import RuntimeAgentBuild
+from .runtime_engine.loading import RuntimeLoading
+from .runtime_engine.observability import setup_smolagents_observability
+from .runtime_engine.policy_registry import MCPPolicyRegistry
+from .runtime_engine.task_flow import RuntimeTaskFlow
+from .runtime_engine.tool_flow import RuntimeToolFlow
+
+
+class ManagedAgentRuntime(
+    RuntimeA2ABridge,
+    RuntimeTaskFlow,
+    RuntimeToolFlow,
+    RuntimeAgentBuild,
+    RuntimeLoading,
+):
+    """单个 agent definition 对应的一份运行时实例。
+
+    这里故意只做门面：
+
+    - 保存 runtime 级状态
+    - 暴露对外方法
+    - 通过 runtime_engine 里的几个职责 mixin 形成完整能力
+    """
+
+    def __init__(
+        self,
+        definition: AgentDefinition,
+        public_base_url: str,
+        discoverer: Callable[..., list[DiscoveredTool]] | None = None,
+    ):
+        self.definition = definition
+        self.public_base_url = public_base_url.rstrip("/")
+        self.discoverer = discoverer or default_discover_tools
+        self.task_pool = TaskPool()
+        self.plugin: BaseAgentPlugin | None = None
+        # 这里只缓存 discovery 阶段的工具摘要，不缓存可执行 tool 实例。
+        self.discovered_tools: list[DiscoveredTool] = []
+        self.load_error: str | None = None
+        self.load_exception: Exception | None = None
+        self._asgi_app = None
+        self._failed_task_ids: set[str] = set()
+        self._tool_source_by_name: dict[str, str] = {}
+        setup_smolagents_observability()
+
+    @property
+    def status(self) -> str:
+        return "error" if self.load_error else "ready"
+
+    def public_url(self) -> str:
+        return self.public_base_url
+
+    @property
+    def _agent(self):
+        return self.definition.agent
+
+    @property
+    def _runtime_config(self):
+        return self.definition.runtime
+
+    @property
+    def _mcps(self):
+        return self.definition.mcps
+
+    @property
+    def _policy_registry(self) -> MCPPolicyRegistry:
+        return MCPPolicyRegistry(self._mcps, self._tool_source_by_name)
+
+    def set_instructions(self, text: str) -> None:
+        self._agent.extra_instructions = text
+
+    def get_instructions(self) -> str:
+        return self._agent.extra_instructions
+
+    def set_tool_policy(
+        self, tool_name: str, policy: ToolPolicy, mcp_name: str | None = None
+    ) -> None:
+        self._policy_registry.set_tool_policy(tool_name, policy, mcp_name)
+
+    def get_tool_policy(
+        self, tool_name: str, mcp_name: str | None = None
+    ) -> ToolPolicy | None:
+        return self._policy_registry.get_tool_policy(tool_name, mcp_name)
+
+    def list_tool_policies(self, mcp_name: str | None = None) -> dict[str, ToolPolicy]:
+        return self._policy_registry.list_tool_policies(mcp_name)
+
+    def remove_tool_policy(self, tool_name: str, mcp_name: str | None = None) -> bool:
+        return self._policy_registry.remove_tool_policy(tool_name, mcp_name)

agent_runtime/runtime_engine/__init__.py

@@ -0,0 +1,22 @@
+"""ManagedAgentRuntime 的内部引擎模块
+
+- `runtime.py` 只保留 runtime 的核心状态和 public API
+- `runtime_engine/` 按职责拆开内部实现，避免所有逻辑都堆在一个大文件里
+
+阅读顺序建议：
+
+1. `loading.py`: reload 时加载 plugin，并发现 MCP 工具
+2. `agent_build.py`: 单次请求到来时，把 model/tools/instructions 组装成 agent
+3. `tool_flow.py`: 工具真正执行前，做缺参补齐和授权确认
+4. `task_flow.py`: 管理任务的启动、等待、恢复、超时、取消、完成
+5. `a2a_bridge.py`: 把 runtime 接到 A2A / ASGI
+
+辅助模块：
+
+- `context.py`: 任务上下文、contextvars、wait state
+- `a2a_task_io.py`: A2A 请求解析和任务消息输出
+- `protocol_tools.py`: ask_user / ask_auth / final_answer 这三个协议工具
+- `policy_registry.py`: MCP 级工具策略的统一读写
+
+这些模块只服务于 runtime 门面，不作为对外 public contract。
+"""

agent_runtime/runtime_engine/a2a_bridge.py

@@ -0,0 +1,190 @@
+"""A2A / ASGI 桥接层。
+
+这个模块把 `ManagedAgentRuntime` 暴露成 A2A server：
+
+- 构建 agent card
+- 创建 A2A 应用
+- 把 A2A 的 execute / cancel 生命周期转发到 runtime task flow
+
+具体的 A2A 请求解析和任务消息组装，已经下沉到 `a2a_task_io.py`。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from .a2a_task_io import (
+    extract_initial_text,
+    extract_request_headers,
+    extract_user_input,
+    publish_error,
+)
+from .context import current_task_id, current_task_pool
+
+
+logger = logging.getLogger(__name__)
+
+
+class RuntimeA2ABridge:
+    """把 runtime 接到 A2A 协议和 ASGI 应用上的桥接层。"""
+
+    def build_agent_card(self):
+        from a2a.types import AgentCapabilities, AgentCard, AgentSkill
+
+        skills = [
+            AgentSkill(
+                id=skill.id,
+                name=skill.name,
+                description=skill.description,
+                tags=skill.tags,
+                examples=skill.examples,
+            )
+            for skill in self._agent.a2a.skills
+        ]
+        return AgentCard(
+            name=self._agent.name,
+            description=self._agent.description,
+            url=self.public_url(),
+            version=self._agent.version,
+            default_input_modes=self._agent.a2a.default_input_modes,
+            default_output_modes=self._agent.a2a.default_output_modes,
+            capabilities=AgentCapabilities(streaming=True),
+            skills=skills,
+        )
+
+    def get_asgi_app(self):
+        if self._asgi_app is None:
+            from a2a.server.apps import A2AStarletteApplication
+            from a2a.server.request_handlers import DefaultRequestHandler
+            from a2a.server.tasks import InMemoryTaskStore
+
+            runtime = self
+            task_store = InMemoryTaskStore()
+            executor = self._build_executor(task_store=task_store)
+
+            class CleanupRequestHandler(DefaultRequestHandler):
+                async def _cleanup_producer(
+                    self, producer_task: asyncio.Task, task_id: str
+                ) -> None:
+                    await super()._cleanup_producer(producer_task, task_id)
+                    if not runtime.pop_failed_task_id(task_id):
+                        return
+                    try:
+                        await self.task_store.delete(task_id)
+                    except Exception:
+                        logger.warning(
+                            "Failed to delete failed task from A2A task_store task_id=%s",
+                            task_id,
+                            exc_info=True,
+                        )
+
+            handler = CleanupRequestHandler(
+                agent_executor=executor, task_store=task_store
+            )
+            self._asgi_app = A2AStarletteApplication(
+                agent_card=self.build_agent_card(),
+                http_handler=handler,
+            ).build()
+        return self._asgi_app
+
+    def _build_executor(self, task_store=None):
+        from a2a.server.agent_execution import AgentExecutor
+        from a2a.server.tasks import TaskUpdater
+
+        class RuntimeExecutor(AgentExecutor):
+            async def execute(self, context, event_queue):
+                main_loop = asyncio.get_running_loop()
+                updater = TaskUpdater(event_queue, context.task_id, context.context_id)
+
+                if not context.task_id:
+                    return
+
+                current_task_id.set(context.task_id)
+                current_task_pool.set(self_runtime.task_pool)
+
+                try:
+                    if not context.current_task:
+                        await self_runtime._start_new_task(
+                            context.task_id,
+                            extract_initial_text(context),
+                            extract_request_headers(context),
+                            main_loop,
+                            updater,
+                            context_id=context.context_id,
+                            task_store=task_store,
+                        )
+
+                    task_info = self_runtime.task_pool.get(context.task_id)
+                    if task_info:
+                        task_info.updater = updater
+                        task_info.loop = main_loop
+
+                    from a2a.types import TaskState
+
+                    await updater.update_status(TaskState.working)
+
+                    user_input = (
+                        extract_user_input(context, task_info)
+                        if context.current_task
+                        else None
+                    )
+                    await self_runtime._run_task_cycle(
+                        context.task_id,
+                        updater,
+                        user_input,
+                        task_store=task_store,
+                    )
+                except Exception as exc:
+                    logger.exception(
+                        "Unhandled task execution error agent_id=%s task_id=%s",
+                        self_runtime._agent.agent_id,
+                        context.task_id,
+                    )
+                    task_info = self_runtime.task_pool.get(context.task_id)
+                    if task_info is not None and not task_info.finalized:
+                        await self_runtime._finalize_task(
+                            context.task_id,
+                            updater,
+                            error=exc,
+                            task_store=task_store,
+                        )
+                    else:
+                        await publish_error(updater, exc)
+
+            async def cancel(self, context, event_queue):
+                if not context.task_id:
+                    return
+
+                task_info = self_runtime.task_pool.get(context.task_id)
+                if not task_info or task_info.finalized:
+                    return
+
+                updater = task_info.updater or TaskUpdater(
+                    event_queue, context.task_id, context.context_id
+                )
+                try:
+                    await self_runtime._cancel_task(
+                        context.task_id,
+                        updater,
+                        task_store=task_store,
+                    )
+                except Exception as exc:
+                    logger.exception(
+                        "Unhandled task cancellation error agent_id=%s task_id=%s",
+                        self_runtime._agent.agent_id,
+                        context.task_id,
+                    )
+                    task_info = self_runtime.task_pool.get(context.task_id)
+                    if task_info is not None and not task_info.finalized:
+                        await self_runtime._finalize_task(
+                            context.task_id,
+                            updater,
+                            error=exc,
+                            task_store=task_store,
+                        )
+                    else:
+                        await publish_error(updater, exc)
+
+        self_runtime = self
+        return RuntimeExecutor()

agent_runtime/runtime_engine/a2a_task_io.py

@@ -0,0 +1,165 @@
+"""A2A 任务传输适配层。
+
+这个模块只处理 A2A 协议相关的任务 I/O：
+
+- 从 A2A context 提取 headers、初始文本、resume 输入
+- 把 runtime 的 wait state / 完成 / 失败结果转成 A2A TaskUpdater 调用
+
+这样 `task_flow.py` 只管任务调度，不再直接依赖 A2A message 细节。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .context import (
+    TaskContext,
+    TaskUpdaterProtocol,
+    WAIT_TYPE_AUTH_REQUIRED,
+    WAIT_TYPE_INPUT_REQUIRED,
+    wait_state_type,
+)
+from ..exceptions import user_message_for_error
+
+
+def extract_request_headers(context: Any) -> dict[str, str]:
+    headers = {}
+    if context.call_context and "headers" in context.call_context.state:
+        headers = context.call_context.state.get("headers") or {}
+    return {
+        "X-Session-Id": headers.get("x-session-id") or headers.get("X-Session-Id", ""),
+        "accessToken": headers.get("accesstoken") or headers.get("accessToken", ""),
+        "user_email": headers.get("user_email", ""),
+    }
+
+
+def extract_initial_text(context: Any) -> str:
+    return "\n".join(
+        part.root.text for part in context.message.parts if part.root.kind == "text"
+    ).strip()
+
+
+_MISSING = object()
+
+
+def extract_user_input(
+    context: Any, task_info: TaskContext | None
+) -> str | dict | bool | None:
+    message = context.message
+    if not message:
+        return None
+
+    text_parts: list[str] = []
+    first_data_part: Any = _MISSING
+    for part in message.parts:
+        root = getattr(part, "root", None)
+        if not root:
+            continue
+        kind = getattr(root, "kind", None)
+        if kind == "text":
+            text = getattr(root, "text", None)
+            if text is not None:
+                text_parts.append(str(text))
+        elif kind == "data" and first_data_part is _MISSING:
+            data = getattr(root, "data", None)
+            if isinstance(data, (dict, bool)):
+                first_data_part = data
+
+    text_input = "\n".join(text_parts).strip() if text_parts else None
+    wait_type = wait_state_type(task_info.wait_item) if task_info else None
+
+    if wait_type == WAIT_TYPE_AUTH_REQUIRED and first_data_part is not _MISSING:
+        return first_data_part
+    if text_input is not None:
+        return text_input
+    if wait_type == WAIT_TYPE_INPUT_REQUIRED and isinstance(first_data_part, dict):
+        for key in ("answer", "text", "input", "value"):
+            value = first_data_part.get(key)
+            if value is not None:
+                return str(value)
+    if isinstance(first_data_part, dict):
+        return first_data_part
+    return None
+
+
+async def emit_wait_state(
+    task_updater: TaskUpdaterProtocol | Any, payload: dict[str, Any]
+) -> None:
+    from a2a.types import Part, TaskState
+
+    wait_type = payload["type"]
+    wait_data = payload["data"]
+
+    if wait_type == WAIT_TYPE_INPUT_REQUIRED:
+        prompt = wait_data.get("prompt")
+        message = None
+        if prompt:
+            message = task_updater.new_agent_message(
+                parts=[Part.model_validate({"text": prompt})],
+                metadata={
+                    "event": wait_type,
+                    "state": TaskState.input_required.value,
+                },
+            )
+        await task_updater.requires_input(message=message)
+        return
+
+    if wait_type == WAIT_TYPE_AUTH_REQUIRED:
+        message = task_updater.new_agent_message(
+            parts=[Part.model_validate({"kind": "data", "data": wait_data})],
+            metadata={
+                "event": wait_type,
+                "state": TaskState.auth_required.value,
+            },
+        )
+        await task_updater.update_status(
+            TaskState.auth_required,
+            message=message,
+            metadata={
+                "event": wait_type,
+                "state": TaskState.auth_required.value,
+            },
+        )
+        return
+
+    raise ValueError(f"unsupported wait state type: {wait_type}")
+
+
+async def publish_message_completion(
+    task_updater: TaskUpdaterProtocol | Any, message_text: str
+) -> None:
+    from a2a.types import Part, TaskState
+
+    message = task_updater.new_agent_message(
+        parts=[Part.model_validate({"text": message_text})],
+        metadata={"event": "completed", "state": TaskState.completed.value},
+    )
+    await task_updater.complete(message=message)
+
+
+async def publish_error(
+    task_updater: TaskUpdaterProtocol | Any, error: Exception
+) -> None:
+    from a2a.types import Part, TaskState
+
+    message = task_updater.new_agent_message(
+        parts=[Part.model_validate({"text": user_message_for_error(error)})],
+        metadata={"event": "failed", "state": TaskState.failed.value},
+    )
+    await task_updater.failed(message=message)
+
+
+async def publish_result(
+    task_updater: TaskUpdaterProtocol | Any, result: Any
+) -> None:
+    from a2a.types import Part, TaskState
+
+    if isinstance(result, dict):
+        parts = [Part.model_validate({"kind": "data", "data": result})]
+    else:
+        parts = [Part.model_validate({"text": str(result)})]
+    message = task_updater.new_agent_message(
+        parts=parts,
+        metadata={"event": "completed", "state": TaskState.completed.value},
+    )
+    await task_updater.complete(message=message)