refactor(super_agent): Apply Dara SDK patches lazily and improve type hints

This change refactors the application of monkey patches to the Dara SDK models and clients, applying them only when needed rather than at module load time. It also improves type hint accuracy for several parameters in both synchronous and asynchronous client methods.

The key changes include:
- Introducing `ensure_super_agent_patches_applied()` function that applies all necessary patches lazily
- Moving placeholder image definition into its own constant
- Updating docstrings for clarity
- Improving parameter types across multiple client method signatures

Co-developed-by: Aone Copilot <noreply@alibaba-inc.com>
Signed-off-by: Sodawyx <sodawyx@126.com>

Author: Sodawyx

agentrun/super_agent/__client_async_template.py

@@ -22,6 +22,7 @@
 from agentrun.agent_runtime.runtime import AgentRuntime
 from agentrun.super_agent.agent import SuperAgent
 from agentrun.super_agent.api.control import (
+    ensure_super_agent_patches_applied,
     from_agent_runtime,
     is_super_agent,
     SUPER_AGENT_TAG,
@@ -86,6 +87,9 @@ class SuperAgentClient:
     """Super Agent CRUDL 客户端."""
 
     def __init__(self, config: Optional[Config] = None) -> None:
+        # 按需打 Dara SDK 兼容补丁 (幂等)。放在本构造函数里, 让 "仅 import
+        # agentrun.super_agent" 的调用方不被动承担全局 SDK 副作用。
+        ensure_super_agent_patches_applied()
         self.config = config
         self._rt = AgentRuntimeClient(config=config)
         # create/update 绕过 AgentRuntimeClient 的 artifact_type 校验 (SUPER_AGENT 不需要 code/container),
@@ -302,19 +306,22 @@ def get(self, name: str, *, config: Optional[Config] = None) -> SuperAgent:
         return agent
 
     # ─── Update (read-merge-write) ─────────────────────
+    # 参数默认值 ``_UNSET`` 是内部哨兵 (object())。为保留 IDE 自动补全与 mypy
+    # 类型检查, 签名保持精确类型标注, 对 ``= _UNSET`` 的赋值加 ``type: ignore``。
+    # 未传 = 保持不变, 显式传 None = 清空字段。
     async def update_async(
         self,
         name: str,
         *,
-        description: Any = _UNSET,
-        prompt: Any = _UNSET,
-        agents: Any = _UNSET,
-        tools: Any = _UNSET,
-        skills: Any = _UNSET,
-        sandboxes: Any = _UNSET,
-        workspaces: Any = _UNSET,
-        model_service_name: Any = _UNSET,
-        model_name: Any = _UNSET,
+        description: Optional[str] = _UNSET,  # type: ignore[assignment]
+        prompt: Optional[str] = _UNSET,  # type: ignore[assignment]
+        agents: Optional[List[str]] = _UNSET,  # type: ignore[assignment]
+        tools: Optional[List[str]] = _UNSET,  # type: ignore[assignment]
+        skills: Optional[List[str]] = _UNSET,  # type: ignore[assignment]
+        sandboxes: Optional[List[str]] = _UNSET,  # type: ignore[assignment]
+        workspaces: Optional[List[str]] = _UNSET,  # type: ignore[assignment]
+        model_service_name: Optional[str] = _UNSET,  # type: ignore[assignment]
+        model_name: Optional[str] = _UNSET,  # type: ignore[assignment]
         config: Optional[Config] = None,
     ) -> SuperAgent:
         """异步更新超级 Agent (read-merge-write)."""
@@ -356,15 +363,15 @@ def update(
         self,
         name: str,
         *,
-        description: Any = _UNSET,
-        prompt: Any = _UNSET,
-        agents: Any = _UNSET,
-        tools: Any = _UNSET,
-        skills: Any = _UNSET,
-        sandboxes: Any = _UNSET,
-        workspaces: Any = _UNSET,
-        model_service_name: Any = _UNSET,
-        model_name: Any = _UNSET,
+        description: Optional[str] = _UNSET,  # type: ignore[assignment]
+        prompt: Optional[str] = _UNSET,  # type: ignore[assignment]
+        agents: Optional[List[str]] = _UNSET,  # type: ignore[assignment]
+        tools: Optional[List[str]] = _UNSET,  # type: ignore[assignment]
+        skills: Optional[List[str]] = _UNSET,  # type: ignore[assignment]
+        sandboxes: Optional[List[str]] = _UNSET,  # type: ignore[assignment]
+        workspaces: Optional[List[str]] = _UNSET,  # type: ignore[assignment]
+        model_service_name: Optional[str] = _UNSET,  # type: ignore[assignment]
+        model_name: Optional[str] = _UNSET,  # type: ignore[assignment]
         config: Optional[Config] = None,
     ) -> SuperAgent:
         """同步更新超级 Agent (read-merge-write)."""

agentrun/super_agent/agui.py

@@ -23,7 +23,7 @@
 
 from __future__ import annotations
 
-from typing import AsyncIterator, Dict, Literal, Optional, Type
+from typing import AsyncGenerator, Dict, Literal, Optional, Type
 
 from ag_ui.core import (
     BaseEvent,
@@ -113,7 +113,7 @@ async def as_agui_events(
     stream: InvokeStream,
     *,
     on_unknown: UnknownMode = "raise",
-) -> AsyncIterator[BaseEvent]:
+) -> AsyncGenerator[BaseEvent, None]:
     """把 :class:`InvokeStream` 中的原始 :class:`SSEEvent` 解码为强类型流.
 
     无论正常消费结束、中途异常、解码异常, 都保证 ``await stream.aclose()`` 被调用

agentrun/super_agent/api/control.py

@@ -14,9 +14,12 @@
 from __future__ import annotations
 
 import json
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
 from urllib.parse import urlparse, urlunparse
 
+if TYPE_CHECKING:
+    from agentrun.super_agent.agent import SuperAgent
+
 from alibabacloud_agentrun20250910.client import Client as _DaraClient
 from alibabacloud_agentrun20250910.models import (
     CreateAgentRuntimeInput as _DaraCreateAgentRuntimeInput,
@@ -60,6 +63,12 @@
 
 _RAM_DATA_DOMAINS = ("agentrun-data", "funagent-data-pre")
 
+# SUPER_AGENT 不跑用户 container/code, 但服务端强制要求 artifact/container_configuration 非空,
+# 这里给一个占位镜像地址即可。region 取杭州仅为了格式合法, 服务端不会实际 pull。
+_PLACEHOLDER_IMAGE = (
+    "registry.cn-hangzhou.aliyuncs.com/agentrun/super-agent-placeholder:v1"
+)
+
 
 # ─── URL 工具 ──────────────────────────────────────────
 
@@ -143,14 +152,23 @@ def model_dump(self, **kwargs: Any) -> Dict[str, Any]:
         return super().model_dump(**kwargs)
 
 
-# ─── Dara 模型猴补丁 ──────────────────────────────────────
-# Dara 的 ``ProtocolConfiguration`` 当前版本没有 ``externalEndpoint`` 字段;
-# ``AgentRuntimeClient.create_async/update_async`` 内部做
-# ``CreateAgentRuntimeInput().from_map(pydantic.model_dump())`` 的 roundtrip,
-# 会在 Dara 层丢失此字段。这里做一次加性 patch: 仅追加读写 ``externalEndpoint``,
-# 不改变任何现有字段行为, 用模块级哨兵属性保证幂等。
+# ─── Dara 模型/客户端猴补丁 ──────────────────────────────────────
+# 当前版 Dara SDK 缺 ``ProtocolConfiguration.externalEndpoint`` 和
+# ``CreateAgentRuntimeInput/UpdateAgentRuntimeInput/ListAgentRuntimesRequest.tags``
+# 字段, 会在 Pydantic ↔ Dara ``from_map / to_map`` roundtrip 中静默丢失; 且
+# ``Client.list_agent_runtimes_with_options{,_async}`` 不会把 ``tags`` 写到 query。
+#
+# 所有补丁都延迟到 ``SuperAgentClient`` 实例化时 (见
+# ``ensure_super_agent_patches_applied``) 才触发, 避免仅 import 本模块的调用方
+# 被动承担全局副作用。补丁本身用哨兵属性保证幂等, 重复调用安全。
+# TODO: 等 Dara SDK 原生支持后删除。
+
+
+def _patch_dara_protocol_configuration() -> None:
+    """补齐 ``ProtocolConfiguration.externalEndpoint`` 的 from_map/to_map 读写."""
+    if getattr(_DaraProtocolConfiguration, "_super_agent_patched", False):
+        return
 
-if not getattr(_DaraProtocolConfiguration, "_super_agent_patched", False):
     _orig_to_map = _DaraProtocolConfiguration.to_map
     _orig_from_map = _DaraProtocolConfiguration.from_map
 
@@ -174,10 +192,8 @@ def _patched_from_map(
     _DaraProtocolConfiguration._super_agent_patched = True  # type: ignore[attr-defined]
 
 
-# Dara 的 ``CreateAgentRuntimeInput`` / ``UpdateAgentRuntimeInput`` 当前版本没有
-# ``tags`` 字段, 与 ``ProtocolConfiguration`` 同理会在 Pydantic → Dara 的 roundtrip
-# 中被静默丢弃. 这里沿用同款加性 patch, 只补齐 ``tags`` 字段的读写.
 def _patch_dara_tags(cls: Any) -> None:
+    """给 Dara model 补齐 ``tags`` 字段的 from_map/to_map 读写."""
     if getattr(cls, "_super_agent_tags_patched", False):
         return
     _orig_to_map = cls.to_map
@@ -201,22 +217,6 @@ def _patched_from_map(self: Any, m: Optional[Dict[str, Any]] = None) -> Any:
     cls._super_agent_tags_patched = True  # type: ignore[attr-defined]
 
 
-_patch_dara_tags(_DaraCreateAgentRuntimeInput)
-_patch_dara_tags(_DaraUpdateAgentRuntimeInput)
-# ``ListAgentRuntimesRequest`` 同样没有 ``tags`` 字段: 补上 from_map/to_map 以保留
-# 属性; 真正让服务端生效的查询参数注入由下面的 client 级补丁完成。
-_patch_dara_tags(_DaraListAgentRuntimesRequest)
-
-
-# ─── Dara 客户端猴补丁: list 请求 query 注入 tags ───────────────
-# 现版 Dara ``Client.list_agent_runtimes_with_options`` 不读 ``request.tags``
-# 构造 query, 导致即便 Pydantic 侧把 tags 传下来, 服务端也收不到。这里一次性
-# 包裹同步 / 异步两个方法: 若 request 带有 ``tags`` 就在底层 ``call_api`` 调用
-# 前把 ``tags`` (列表 → 逗号分隔) 追加到 ``req.query``。
-# 每个 API 调用都会 ``_get_client()`` 新建 ``Client`` 实例, 实例属性级别的替换
-# 在并发下是安全的。
-
-
 def _tags_query_value(tags: Any) -> Optional[str]:
     if tags is None:
         return None
@@ -228,6 +228,13 @@ def _tags_query_value(tags: Any) -> Optional[str]:
 
 
 def _patch_dara_client_list_tags() -> None:
+    """包裹 ``Client.list_agent_runtimes_with_options{,_async}``: 若 request 带
+    ``tags`` 就在底层 ``call_api`` 调用前把 ``tags`` (列表 → 逗号分隔) 追加到
+    ``req.query``。
+
+    每次 API 调用由 ``_get_client()`` 新建 ``Client`` 实例, 实例属性级别的
+    ``self.call_api = _injecting`` 替换在并发下是安全的。
+    """
     if getattr(_DaraClient, "_super_agent_list_tags_patched", False):
         return
 
@@ -285,7 +292,20 @@ async def _injecting(params: Any, req: Any, rt: Any) -> Any:
     _DaraClient._super_agent_list_tags_patched = True  # type: ignore[attr-defined]
 
 
-_patch_dara_client_list_tags()
+def ensure_super_agent_patches_applied() -> None:
+    """按需应用全部 Dara SDK 兼容补丁 (幂等)。
+
+    由 ``SuperAgentClient.__init__`` 调用。如果调用方直接使用
+    ``to_create_input`` / ``to_update_input`` 并自己构造 ``CreateAgentRuntimeInput``
+    / ``ListAgentRuntimesRequest``, 也应在 Pydantic → Dara 转换前调用一次本函数。
+    """
+    _patch_dara_protocol_configuration()
+    _patch_dara_tags(_DaraCreateAgentRuntimeInput)
+    _patch_dara_tags(_DaraUpdateAgentRuntimeInput)
+    # ``ListAgentRuntimesRequest`` 补齐 from_map/to_map 保留属性; 真正让服务端
+    # 生效的 query 注入由 ``_patch_dara_client_list_tags`` 完成。
+    _patch_dara_tags(_DaraListAgentRuntimesRequest)
+    _patch_dara_client_list_tags()
 
 
 # ─── AgentRuntime ↔ SuperAgent 转换 ────────────────────────
@@ -392,9 +412,7 @@ def to_create_input(
         external_agent_endpoint_url=build_super_agent_endpoint(cfg),
         # 占位 artifact: SUPER_AGENT 不跑用户 container/code, 但服务端要求非空。
         artifact_type=AgentRuntimeArtifact.CONTAINER,
-        container_configuration=AgentRuntimeContainer(
-            image="registry.cn-hangzhou.aliyuncs.com/agentrun/super-agent-placeholder:v1"
-        ),
+        container_configuration=AgentRuntimeContainer(image=_PLACEHOLDER_IMAGE),
         network_configuration=NetworkConfig(network_mode=NetworkMode.PUBLIC),
     )
 
@@ -425,9 +443,7 @@ def to_update_input(
         external_agent_endpoint_url=build_super_agent_endpoint(cfg),
         # 占位 artifact: SUPER_AGENT 不跑用户 container/code, 但服务端要求非空。
         artifact_type=AgentRuntimeArtifact.CONTAINER,
-        container_configuration=AgentRuntimeContainer(
-            image="registry.cn-hangzhou.aliyuncs.com/agentrun/super-agent-placeholder:v1"
-        ),
+        container_configuration=AgentRuntimeContainer(image=_PLACEHOLDER_IMAGE),
         network_configuration=NetworkConfig(network_mode=NetworkMode.PUBLIC),
     )
 
@@ -502,7 +518,7 @@ def _get_external_endpoint(rt: AgentRuntime) -> str:
     )
 
 
-def from_agent_runtime(rt: AgentRuntime) -> "SuperAgent":  # noqa: F821
+def from_agent_runtime(rt: AgentRuntime) -> "SuperAgent":
     """反解 AgentRuntime → SuperAgent 实例 (不注入 ``_client``)."""
     # 延迟导入避免循环
     from agentrun.super_agent.agent import SuperAgent
@@ -547,4 +563,5 @@ def from_agent_runtime(rt: AgentRuntime) -> "SuperAgent":  # noqa: F821
     "from_agent_runtime",
     "is_super_agent",
     "parse_super_agent_config",
+    "ensure_super_agent_patches_applied",
 ]

agentrun/super_agent/client.py

@@ -32,6 +32,7 @@
 from agentrun.agent_runtime.runtime import AgentRuntime
 from agentrun.super_agent.agent import SuperAgent
 from agentrun.super_agent.api.control import (
+    ensure_super_agent_patches_applied,
     from_agent_runtime,
     is_super_agent,
     SUPER_AGENT_TAG,
@@ -96,6 +97,9 @@ class SuperAgentClient:
     """Super Agent CRUDL 客户端."""
 
     def __init__(self, config: Optional[Config] = None) -> None:
+        # 按需打 Dara SDK 兼容补丁 (幂等)。放在本构造函数里, 让 "仅 import
+        # agentrun.super_agent" 的调用方不被动承担全局 SDK 副作用。
+        ensure_super_agent_patches_applied()
         self.config = config
         self._rt = AgentRuntimeClient(config=config)
         # create/update 绕过 AgentRuntimeClient 的 artifact_type 校验 (SUPER_AGENT 不需要 code/container),
@@ -312,19 +316,22 @@ def get(self, name: str, *, config: Optional[Config] = None) -> SuperAgent:
         return agent
 
     # ─── Update (read-merge-write) ─────────────────────
+    # 参数默认值 ``_UNSET`` 是内部哨兵 (object())。为保留 IDE 自动补全与 mypy
+    # 类型检查, 签名保持精确类型标注, 对 ``= _UNSET`` 的赋值加 ``type: ignore``。
+    # 未传 = 保持不变, 显式传 None = 清空字段。
     async def update_async(
         self,
         name: str,
         *,
-        description: Any = _UNSET,
-        prompt: Any = _UNSET,
-        agents: Any = _UNSET,
-        tools: Any = _UNSET,
-        skills: Any = _UNSET,
-        sandboxes: Any = _UNSET,
-        workspaces: Any = _UNSET,
-        model_service_name: Any = _UNSET,
-        model_name: Any = _UNSET,
+        description: Optional[str] = _UNSET,  # type: ignore[assignment]
+        prompt: Optional[str] = _UNSET,  # type: ignore[assignment]
+        agents: Optional[List[str]] = _UNSET,  # type: ignore[assignment]
+        tools: Optional[List[str]] = _UNSET,  # type: ignore[assignment]
+        skills: Optional[List[str]] = _UNSET,  # type: ignore[assignment]
+        sandboxes: Optional[List[str]] = _UNSET,  # type: ignore[assignment]
+        workspaces: Optional[List[str]] = _UNSET,  # type: ignore[assignment]
+        model_service_name: Optional[str] = _UNSET,  # type: ignore[assignment]
+        model_name: Optional[str] = _UNSET,  # type: ignore[assignment]
         config: Optional[Config] = None,
     ) -> SuperAgent:
         """异步更新超级 Agent (read-merge-write)."""
@@ -366,15 +373,15 @@ def update(
         self,
         name: str,
         *,
-        description: Any = _UNSET,
-        prompt: Any = _UNSET,
-        agents: Any = _UNSET,
-        tools: Any = _UNSET,
-        skills: Any = _UNSET,
-        sandboxes: Any = _UNSET,
-        workspaces: Any = _UNSET,
-        model_service_name: Any = _UNSET,
-        model_name: Any = _UNSET,
+        description: Optional[str] = _UNSET,  # type: ignore[assignment]
+        prompt: Optional[str] = _UNSET,  # type: ignore[assignment]
+        agents: Optional[List[str]] = _UNSET,  # type: ignore[assignment]
+        tools: Optional[List[str]] = _UNSET,  # type: ignore[assignment]
+        skills: Optional[List[str]] = _UNSET,  # type: ignore[assignment]
+        sandboxes: Optional[List[str]] = _UNSET,  # type: ignore[assignment]
+        workspaces: Optional[List[str]] = _UNSET,  # type: ignore[assignment]
+        model_service_name: Optional[str] = _UNSET,  # type: ignore[assignment]
+        model_name: Optional[str] = _UNSET,  # type: ignore[assignment]
         config: Optional[Config] = None,
     ) -> SuperAgent:
         """同步更新超级 Agent (read-merge-write)."""

tests/unittests/super_agent/test_control.py

@@ -10,6 +10,7 @@
     _add_ram_prefix_to_host,
     API_VERSION,
     build_super_agent_endpoint,
+    ensure_super_agent_patches_applied,
     EXTERNAL_TAG,
     from_agent_runtime,
     is_super_agent,
@@ -23,6 +24,10 @@
 from agentrun.super_agent.api.data import SuperAgentDataAPI
 from agentrun.utils.config import Config
 
+# 本文件部分测试 (list request tags 补丁) 依赖 Dara SDK 已被打过补丁,
+# 显式在模块加载时触发补丁 (幂等, 与 SuperAgentClient.__init__ 内触发点一致)。
+ensure_super_agent_patches_applied()
+
 # ─── build_super_agent_endpoint ────────────────────────────────
 
 
@@ -282,7 +287,7 @@ def test_to_update_input_full_protocol_replace():
 
 
 # ─── Dara ListAgentRuntimesRequest tags 补丁 ──────────────────
-# 同时确保 import agentrun.super_agent.api.control 已应用补丁 (已在文件顶部导入)。
+# 补丁已在模块顶部通过 ensure_super_agent_patches_applied() 显式触发。
 
 
 def test_list_request_from_map_preserves_tags():