feat(super_agent): Add new super agent module and related APIs by Sodawyx · Pull Request #84 · Serverless-Devs/agentrun-sdk-python

Sodawyx · 2026-04-16T11:50:02Z

This commit introduces the super_agent module with its core components including models, API handlers, clients, and streaming functionality. It also adds corresponding unit tests to ensure proper functionality of the new features.

Key changes include:

Added model.py, api/ directory with control and data modules
Introduced agent.py, client.py, stream.py, and template files
Updated tool.py to improve parameter description handling
Modified existing client methods in agent_runtime/client.py and __client_async_template.py
Extended agent_runtime/model.py to support SUPER_AGENT protocol
Improved test cases for better coverage
Updated package exports in __init__.py to expose new super agent classes and functions

Co-developed-by: Aone Copilot [email protected]

Thank you for creating a pull request to contribute to Serverless Devs agentrun-sdk-python code! Before you open the request please answer the following questions to help it be more easily integrated. Please check the boxes "[ ]" with "[x]" when done too.
Please select one of the PR types below to complete

Fix bugs

Bug detail

The specific manifestation of the bug or the associated issue.

Pull request tasks

Add test cases for the changes
Passed the CI test

Update docs

Reason for update

Why do you need to update your documentation?

Pull request tasks

Update Chinese documentation
Update English documentation

Add contributor

Contributed content

Code
Document

Content detail

if content_type == 'code' || content_type == 'document':
    please tell us `PR url`，like: https://github.com/Serverless-Devs/agentrun-sdk-python/pull/1
else:
    please describe your contribution in detail

Others

Reason for update

Why do you need to update your documentation?

This commit introduces the `super_agent` module with its core components including models, API handlers, clients, and streaming functionality. It also adds corresponding unit tests to ensure proper functionality of the new features. Key changes include: - Added `model.py`, `api/` directory with control and data modules - Introduced `agent.py`, `client.py`, `stream.py`, and template files - Updated `tool.py` to improve parameter description handling - Modified existing client methods in `agent_runtime/client.py` and `__client_async_template.py` - Extended `agent_runtime/model.py` to support SUPER_AGENT protocol - Improved test cases for better coverage - Updated package exports in `__init__.py` to expose new super agent classes and functions Co-developed-by: Aone Copilot <[email protected]> Signed-off-by: Sodawyx <[email protected]>

Copilot

Pull request overview

Adds a new super_agent module that provides a first-class Super Agent SDK layer (CRUDL client, agent invocation with SSE streaming, and optional AG-UI decoding) plus supporting control/data-plane utilities and tests.

Changes:

Introduces agentrun.super_agent package: models, streaming (SSE), agent instance APIs, CRUDL client, and AG-UI adapter.
Adds control-plane helpers (endpoint building, AgentRuntime↔SuperAgent mapping) and data-plane API client for invoke/stream/conversation management.
Updates existing runtime/tooling code and extends unit/integration tests to cover the new module and related behaviors.

Reviewed changes

Copilot reviewed 26 out of 27 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/unittests/toolset/api/test_openapi.py	Normalizes OpenAPI test fixtures formatting for `$ref`/URLs.
tests/unittests/super_agent/test_stream.py	Adds unit tests for SSE parsing and `InvokeStream` lifecycle.
tests/unittests/super_agent/test_no_coupling.py	Adds tests to ensure `super_agent` doesn’t depend on `conversation_service`.
tests/unittests/super_agent/test_data_api.py	Adds coverage for SuperAgent data-plane invoke/stream/conversation APIs.
tests/unittests/super_agent/test_control.py	Adds coverage for control helpers, endpoint construction, and Dara monkey-patches.
tests/unittests/super_agent/test_client.py	Adds coverage for SuperAgent CRUDL client (sync/async, pagination, error paths).
tests/unittests/super_agent/test_agui.py	Adds tests for SSE→AG-UI event decoding and adapter behavior.
tests/unittests/super_agent/test_agent.py	Adds tests for `SuperAgent` instance APIs (invoke, conversation ops, signatures).
tests/unittests/super_agent/init.py	Adds package marker for super_agent unit tests.
tests/unittests/integration/test_langchain_agui_integration.py	Minor fixture formatting changes in integration tests.
agentrun/super_agent/stream.py	Implements SSE parsing and `InvokeStream` async-iterator wrapper with close support.
agentrun/super_agent/model.py	Adds Super Agent dataclass models (inputs, invoke response, conversation info/messages).
agentrun/super_agent/client.py	Adds SuperAgent CRUDL client (sync/async) built on AgentRuntime control/list APIs.
agentrun/super_agent/api/data.py	Adds SuperAgent data-plane API client for invoke/stream/get/delete conversation.
agentrun/super_agent/api/control.py	Adds control-plane helpers + Dara monkey-patches for tags/externalEndpoint and list tags query injection.
agentrun/super_agent/api/init.py	Exposes internal SuperAgent API surface.
agentrun/super_agent/api/__data_async_template.py	Adds codegen template for data-plane API implementation.
agentrun/super_agent/agui.py	Adds AG-UI adapter to decode SSE events into `ag_ui.core` typed events.
agentrun/super_agent/agent.py	Adds `SuperAgent` instance object with async-only invoke and conversation management.
agentrun/super_agent/init.py	Exposes Super Agent public exports (client, agent, stream/models).
agentrun/super_agent/__client_async_template.py	Adds codegen template for SuperAgent client.
agentrun/super_agent/__agent_async_template.py	Adds codegen template for SuperAgent instance.
agentrun/integration/utils/tool.py	Adjusts OpenAPI parameter description handling (prefers param description).
agentrun/agent_runtime/model.py	Extends `AgentRuntimeProtocolType` with `SUPER_AGENT`.
agentrun/agent_runtime/client.py	Changes delete return mapping to avoid enum validation failures on sparse delete responses.
agentrun/agent_runtime/__client_async_template.py	Mirrors delete return mapping change in template.
agentrun/init.py	Exports Super Agent classes/models at package root.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-16T11:57:02Z

+    """承载 ``protocol_settings`` + ``external_endpoint`` 的 Pydantic 扩展.
+
+    基类 ``AgentRuntimeProtocolConfig`` 的 ``type`` 字段是 ``HTTP / MCP`` 枚举,
+    本子类通过 ``model_construct`` 绕过校验存入字符串 ``"SUPER_AGENT"``。


The docstring for SuperAgentProtocolConfig says the base AgentRuntimeProtocolConfig.type only supports HTTP / MCP and that model_construct is used to bypass validation. But AgentRuntimeProtocolType now includes SUPER_AGENT (agentrun/agent_runtime/model.py), so this comment is no longer accurate. Please update the comment (and optionally use the enum value directly) to avoid misleading future maintainers.

Suggested change

"""承载 ``protocol_settings`` + ``external_endpoint`` 的 Pydantic 扩展.

基类 ``AgentRuntimeProtocolConfig`` 的 ``type`` 字段是 ``HTTP / MCP`` 枚举,

本子类通过 ``model_construct`` 绕过校验存入字符串 ``"SUPER_AGENT"``。

"""承载 Super Agent 所需 ``protocol_settings`` + ``external_endpoint`` 的 Pydantic 扩展.

基类 ``AgentRuntimeProtocolConfig`` 已支持 ``SUPER_AGENT`` 类型, 因此这里不再依赖

绕过 ``type`` 校验的特殊约定；本子类仅补充 Super Agent 场景需要的扩展字段。

Copilot · 2026-04-16T11:57:03Z

+"""Unit tests for ``agentrun.super_agent.stream``."""
+
+from typing import List
+from unittest.mock import MagicMock


MagicMock is imported but not used in this test module. Please remove the unused import to keep the test code tidy.

Suggested change

from unittest.mock import MagicMock

Copilot · 2026-04-16T11:57:03Z

+        # ``forwarded_extras`` 承载从 AgentRuntime 元数据读出的业务字段
+        # (prompt/agents/tools/skills/sandboxes/workspaces/modelServiceName/modelName),
+        # 由上层 ``SuperAgent.invoke_async`` 注入。``metadata`` 和 ``conversationId``
+        # 由 SDK 管理, 不允许 extras 覆盖。
+        forwarded: Dict[str, Any] = dict(forwarded_extras or {})
+        forwarded["metadata"] = {"agentRuntimeName": self.agent_runtime_name}
+        if conversation_id is not None:
+            forwarded["conversationId"] = conversation_id
+        return {"messages": list(messages), "forwardedProps": forwarded}


forwarded_extras is copied verbatim into forwardedProps, and conversationId is only overwritten when the conversation_id argument is non-None. That means a direct caller of SuperAgentDataAPI.invoke_async(..., forwarded_extras={"conversationId": ...}) can still inject/spoof conversationId when conversation_id is omitted, contradicting the comment that conversationId is SDK-managed. Consider always removing conversationId from forwarded_extras (e.g., pop it) and only setting it from the conversation_id parameter when provided.

Copilot · 2026-04-16T11:57:03Z

+        logger.debug("super_agent invoke request: POST %s body=%s", url, body)
+
+        async with httpx.AsyncClient(timeout=cfg.get_timeout()) as client:
+            resp = await client.post(
+                url, headers=signed_headers, content=body_bytes
+            )
+            resp.raise_for_status()
+            payload = resp.json()
+        logger.debug(
+            "super_agent invoke response: status=%d payload=%s",
+            resp.status_code,
+            payload,
+        )


The debug logs include the full invoke request body (messages + forwardedProps) and full JSON response payload. These can contain sensitive user content and should generally not be logged verbatim, even at debug level. Suggest logging only high-level metadata (URL, conversationId, status code) and/or truncating/redacting bodies (e.g., length-limited previews) to reduce accidental secret leakage.

… 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 <[email protected]> Signed-off-by: Sodawyx <[email protected]>

This commit introduces the `list_conversations_async` method to both the `SuperAgent` and template classes. The method allows listing conversations asynchronously with optional metadata filtering. By default, it filters by agent runtime name unless explicitly overridden. Key changes include: - Added async implementation in `agent.py`, `__agent_async_template.py`, and API modules - Includes proper error handling and type validation - Maintains backward compatibility through synchronous placeholder methods that raise NotImplementedError Co-developed-by: Aone Copilot <[email protected]> Signed-off-by: Sodawyx <[email protected]>

Updated query parameter decoding to use unquote_plus instead of unquote for better handling of '+' characters in URLs. This change ensures that query parameters are decoded correctly, aligning with standard URL encoding practices. 修复(ram_signature)：使用 unquote_plus 解码查询参数更新查询参数解码，改用 unquote_plus 代替 unquote，以更好地处理 URL 中的 '+' 字符。此更改确保查询参数正确解码，符合标准 URL 编码实践。 Change-Id: I6d8af91c3ac3512cf8b9a96dda4501a643e8fa66 Signed-off-by: OhYee <[email protected]>

…cess This change updates the `SUPER_AGENT_TAG` constant from `"x-agentrun-super-agent"` to `"x-agentrun-super"`, removes the `EXTERNAL_TAG` from the default tags when creating a super agent runtime, and adds clarifying comments about the purpose of `external_agent_endpoint_url`. The corresponding unit tests have also been updated accordingly. Co-developed-by: Aone Copilot <[email protected]> Signed-off-by: Sodawyx <[email protected]>

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 <[email protected]> Signed-off-by: Sodawyx <[email protected]>

Sodawyx requested a review from Copilot April 16, 2026 11:50

Copilot AI reviewed Apr 16, 2026

View reviewed changes

Sodawyx and others added 5 commits April 16, 2026 20:34

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(super_agent): Add new super agent module and related APIs#84

feat(super_agent): Add new super agent module and related APIs#84
Sodawyx wants to merge 6 commits intomainfrom
add-super-agent

Sodawyx commented Apr 16, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Sodawyx commented Apr 16, 2026

Fix bugs

Update docs

Add contributor

Others

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants