refactor(super_agent): Update config structure and parsing logic

This change updates the internal configuration structure to include nested `headers`, `body`, and `forwardedProps`. It also refactors the parsing logic in `_flatten_protocol_config()` to handle both old and new formats seamlessly. The unit tests have been updated accordingly.

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

Author: Sodawyx

agentrun/super_agent/api/control.py

@@ -337,9 +337,12 @@ def _business_fields_from_args(
 def _build_protocol_settings_config(
     *, name: str, business: Dict[str, Any]
 ) -> str:
-    """构造 ``protocolSettings[0].config`` 的 JSON 字符串."""
-    cfg_dict: Dict[str, Any] = {
-        "path": SUPER_AGENT_INVOKE_PATH,
+    """构造 ``protocolSettings[0].config`` 的 JSON 字符串.
+
+    新结构: 顶层 ``path`` / ``headers`` / ``body``, 业务字段收拢到
+    ``body.forwardedProps`` (开放字典, 语义 "any, merge")。
+    """
+    forwarded_props: Dict[str, Any] = {
         "prompt": business.get("prompt"),
         "agents": business.get("agents") or [],
         "tools": business.get("tools") or [],
@@ -350,6 +353,11 @@ def _build_protocol_settings_config(
         "modelName": business.get("modelName"),
         "metadata": {"agentRuntimeName": name},
     }
+    cfg_dict: Dict[str, Any] = {
+        "path": SUPER_AGENT_INVOKE_PATH,
+        "headers": {},
+        "body": {"forwardedProps": forwarded_props},
+    }
     return json.dumps(cfg_dict, ensure_ascii=False)
 
 
@@ -483,10 +491,31 @@ def is_super_agent(rt: AgentRuntime) -> bool:
     return first.get("type") == SUPER_AGENT_PROTOCOL_TYPE
 
 
+def _flatten_protocol_config(cfg: Any) -> Dict[str, Any]:
+    """把 ``protocolSettings[0].config`` 解析结果压平为扁平业务字段 dict.
+
+    兼容两种物理布局:
+    - 新: ``{"path": ..., "headers": ..., "body": {"forwardedProps": {...}}}``
+    - 旧: 业务字段直接在根 (历史 AgentRuntime, 迁移前写入)
+
+    两种结构都返回扁平的业务字段 dict, 上游
+    :func:`from_agent_runtime` 无需感知物理布局差异。
+    """
+    if not isinstance(cfg, dict):
+        return {}
+    body = cfg.get("body")
+    if isinstance(body, dict):
+        forwarded = body.get("forwardedProps")
+        if isinstance(forwarded, dict):
+            return forwarded
+    return cfg
+
+
 def parse_super_agent_config(rt: AgentRuntime) -> Dict[str, Any]:
-    """反解 ``protocolSettings[0].config`` 为业务字段 dict.
+    """反解 ``protocolSettings[0].config`` 为扁平业务字段 dict.
 
     如果 config 缺失或非法 JSON, 返回空 dict (不抛异常)。
+    新旧嵌套布局由 :func:`_flatten_protocol_config` 统一拍平。
     """
     pc_dict = _extract_protocol_configuration(rt)
     if not pc_dict:
@@ -499,13 +528,13 @@ def parse_super_agent_config(rt: AgentRuntime) -> Dict[str, Any]:
     if not raw_config:
         return {}
     if isinstance(raw_config, dict):
-        return raw_config
+        return _flatten_protocol_config(raw_config)
     if isinstance(raw_config, str):
         try:
             parsed = json.loads(raw_config)
-            return parsed if isinstance(parsed, dict) else {}
         except (TypeError, ValueError):
             return {}
+        return _flatten_protocol_config(parsed)
     return {}
 
 

tests/unittests/super_agent/test_client.py

@@ -60,15 +60,20 @@ def _fake_rt(
     """Build a minimal AgentRuntime-like object for ``from_agent_runtime``."""
     cfg_dict = {
         "path": "/invoke",
-        "prompt": prompt,
-        "agents": [],
-        "tools": tools if tools is not None else [],
-        "skills": [],
-        "sandboxes": [],
-        "workspaces": [],
-        "modelServiceName": None,
-        "modelName": None,
-        "metadata": {"agentRuntimeName": name},
+        "headers": {},
+        "body": {
+            "forwardedProps": {
+                "prompt": prompt,
+                "agents": [],
+                "tools": tools if tools is not None else [],
+                "skills": [],
+                "sandboxes": [],
+                "workspaces": [],
+                "modelServiceName": None,
+                "modelName": None,
+                "metadata": {"agentRuntimeName": name},
+            }
+        },
     }
     pc = {
         "type": protocol_type,
@@ -124,7 +129,7 @@ async def _create_async(dara_input, config=None):
     first = pc.protocol_settings[0]
     assert first.type == SUPER_AGENT_PROTOCOL_TYPE
     cfg_json = json.loads(first.config)
-    assert cfg_json["prompt"] == "new"
+    assert cfg_json["body"]["forwardedProps"]["prompt"] == "new"
     assert agent.name == "alpha"
 
 
@@ -206,8 +211,9 @@ async def _update(agent_id, dara_input, config=None):
     cfg_json = json.loads(
         captured["dara"].protocol_configuration.protocol_settings[0].config
     )
-    assert cfg_json["prompt"] == "new"
-    assert cfg_json["tools"] == ["t1"]
+    forwarded = cfg_json["body"]["forwardedProps"]
+    assert forwarded["prompt"] == "new"
+    assert forwarded["tools"] == ["t1"]
 
 
 async def test_update_async_explicit_none_clears_field():
@@ -238,7 +244,7 @@ async def _update(agent_id, dara_input, config=None):
     cfg_json = json.loads(
         captured["dara"].protocol_configuration.protocol_settings[0].config
     )
-    assert cfg_json["prompt"] is None
+    assert cfg_json["body"]["forwardedProps"]["prompt"] is None
 
 
 async def test_update_async_multiple_fields():
@@ -271,8 +277,9 @@ async def _update(agent_id, dara_input, config=None):
     cfg_json = json.loads(
         captured["dara"].protocol_configuration.protocol_settings[0].config
     )
-    assert cfg_json["prompt"] == "p"
-    assert cfg_json["tools"] == ["a", "b"]
+    forwarded = cfg_json["body"]["forwardedProps"]
+    assert forwarded["prompt"] == "p"
+    assert forwarded["tools"] == ["a", "b"]
     assert captured["dara"].description == "d"
 
 

tests/unittests/super_agent/test_control.py

@@ -116,8 +116,10 @@ def test_to_create_input_minimal():
     assert len(settings) == 1
     cfg_dict = json.loads(settings[0]["config"])
     assert cfg_dict["path"] == "/invoke"
-    assert cfg_dict["agents"] == []
-    assert cfg_dict["metadata"] == {"agentRuntimeName": "alpha"}
+    assert cfg_dict["headers"] == {}
+    forwarded = cfg_dict["body"]["forwardedProps"]
+    assert forwarded["agents"] == []
+    assert forwarded["metadata"] == {"agentRuntimeName": "alpha"}
 
 
 def test_to_create_input_full():
@@ -136,14 +138,17 @@ def test_to_create_input_full():
     )
     pc_dict = inp.model_dump()["protocolConfiguration"]
     settings_cfg = json.loads(pc_dict["protocolSettings"][0]["config"])
-    assert settings_cfg["prompt"] == "hello"
-    assert settings_cfg["agents"] == ["a1"]
-    assert settings_cfg["tools"] == ["t1", "t2"]
-    assert settings_cfg["skills"] == ["s1"]
-    assert settings_cfg["sandboxes"] == ["sb1"]
-    assert settings_cfg["workspaces"] == ["ws1"]
-    assert settings_cfg["modelServiceName"] == "foo"
-    assert settings_cfg["modelName"] == "bar"
+    assert settings_cfg["path"] == "/invoke"
+    assert settings_cfg["headers"] == {}
+    forwarded = settings_cfg["body"]["forwardedProps"]
+    assert forwarded["prompt"] == "hello"
+    assert forwarded["agents"] == ["a1"]
+    assert forwarded["tools"] == ["t1", "t2"]
+    assert forwarded["skills"] == ["s1"]
+    assert forwarded["sandboxes"] == ["sb1"]
+    assert forwarded["workspaces"] == ["ws1"]
+    assert forwarded["modelServiceName"] == "foo"
+    assert forwarded["modelName"] == "bar"
 
 
 def test_to_create_input_tags_fixed():
@@ -158,7 +163,9 @@ def test_to_create_input_metadata_only_agent_runtime_name():
     settings_cfg = json.loads(
         inp.protocol_configuration.protocol_settings[0]["config"]
     )
-    assert settings_cfg["metadata"] == {"agentRuntimeName": "d"}
+    assert settings_cfg["body"]["forwardedProps"]["metadata"] == {
+        "agentRuntimeName": "d"
+    }
 
 
 def test_to_create_input_uses_pre_environment_endpoint():
@@ -194,15 +201,21 @@ def _make_rt(**kwargs):
 
 def test_from_agent_runtime():
     config_json = json.dumps({
-        "prompt": "hi",
-        "agents": ["a"],
-        "tools": ["t"],
-        "skills": [],
-        "sandboxes": [],
-        "workspaces": [],
-        "modelServiceName": "svc",
-        "modelName": "mod",
-        "metadata": {"agentRuntimeName": "foo"},
+        "path": "/invoke",
+        "headers": {},
+        "body": {
+            "forwardedProps": {
+                "prompt": "hi",
+                "agents": ["a"],
+                "tools": ["t"],
+                "skills": [],
+                "sandboxes": [],
+                "workspaces": [],
+                "modelServiceName": "svc",
+                "modelName": "mod",
+                "metadata": {"agentRuntimeName": "foo"},
+            }
+        },
     })
     pc = {
         "type": SUPER_AGENT_PROTOCOL_TYPE,
@@ -227,6 +240,89 @@ def test_from_agent_runtime():
     )
 
 
+def test_from_agent_runtime_legacy_flat_config():
+    """旧结构兼容: config 是扁平 dict, 业务字段直接在根 (历史 AgentRuntime)."""
+    config_json = json.dumps({
+        "prompt": "legacy",
+        "agents": ["la"],
+        "tools": ["lt"],
+        "skills": [],
+        "sandboxes": [],
+        "workspaces": [],
+        "modelServiceName": "legacy-svc",
+        "modelName": "legacy-mod",
+        "metadata": {"agentRuntimeName": "legacy"},
+    })
+    pc = {
+        "type": SUPER_AGENT_PROTOCOL_TYPE,
+        "protocolSettings": [{
+            "type": SUPER_AGENT_PROTOCOL_TYPE,
+            "config": config_json,
+            "name": "legacy",
+            "path": "/invoke",
+        }],
+        "externalEndpoint": "https://x.com/super-agents/__SUPER_AGENT__",
+    }
+    rt = _make_rt(agent_runtime_name="legacy", protocol_configuration=pc)
+    agent = from_agent_runtime(rt)
+    assert agent.prompt == "legacy"
+    assert agent.agents == ["la"]
+    assert agent.model_service_name == "legacy-svc"
+
+
+def test_parse_super_agent_config_dict_config_new_structure():
+    """config 已经是 dict (非字符串) 时也能拍平."""
+    pc = {
+        "type": SUPER_AGENT_PROTOCOL_TYPE,
+        "protocolSettings": [{
+            "type": SUPER_AGENT_PROTOCOL_TYPE,
+            "config": {
+                "path": "/invoke",
+                "headers": {},
+                "body": {
+                    "forwardedProps": {
+                        "prompt": "p",
+                        "agents": [],
+                    }
+                },
+            },
+        }],
+    }
+    business = parse_super_agent_config(_make_rt(protocol_configuration=pc))
+    assert business["prompt"] == "p"
+    assert business["agents"] == []
+
+
+def test_parse_super_agent_config_dict_config_legacy_flat():
+    """config 是 dict + 旧扁平结构时走 fallback, 原样返回."""
+    pc = {
+        "type": SUPER_AGENT_PROTOCOL_TYPE,
+        "protocolSettings": [{
+            "type": SUPER_AGENT_PROTOCOL_TYPE,
+            "config": {"prompt": "legacy-dict", "agents": ["la"]},
+        }],
+    }
+    business = parse_super_agent_config(_make_rt(protocol_configuration=pc))
+    assert business == {"prompt": "legacy-dict", "agents": ["la"]}
+
+
+def test_flatten_protocol_config_non_dict_returns_empty():
+    """非 dict 输入 (防御分支) 返回空 dict."""
+    from agentrun.super_agent.api.control import _flatten_protocol_config
+
+    assert _flatten_protocol_config(None) == {}
+    assert _flatten_protocol_config("not-a-dict") == {}
+    assert _flatten_protocol_config([1, 2, 3]) == {}
+
+
+def test_flatten_protocol_config_body_without_forwarded_props():
+    """body 存在但缺 forwardedProps → fallback 到整个 cfg (旧结构)."""
+    from agentrun.super_agent.api.control import _flatten_protocol_config
+
+    cfg = {"body": {"other": "x"}, "prompt": "flat"}
+    assert _flatten_protocol_config(cfg) == cfg
+
+
 def test_is_super_agent_true():
     pc = {
         "type": SUPER_AGENT_PROTOCOL_TYPE,
@@ -280,10 +376,11 @@ def test_to_update_input_full_protocol_replace():
     assert inp.description == "new"
     settings = inp.protocol_configuration.protocol_settings
     assert len(settings) == 1
-    assert (
-        json.loads(settings[0]["config"])["metadata"]["agentRuntimeName"]
-        == "alpha"
-    )
+    cfg_json = json.loads(settings[0]["config"])
+    forwarded = cfg_json["body"]["forwardedProps"]
+    assert forwarded["metadata"]["agentRuntimeName"] == "alpha"
+    assert forwarded["prompt"] == "p"
+    assert forwarded["tools"] == ["t"]
 
 
 # ─── Dara ListAgentRuntimesRequest tags 补丁 ──────────────────