Fix agui (#23)

* fix(credential): correct typo in access key secret parameter name

fix(agui_protocol): optimize import statements and event handling logic

- Move imports to local scope to avoid unnecessary dependencies
- Simplify conditional expressions and method calls
- Improve type hinting for better code clarity

修复凭据模型中的访问密钥参数拼写错误

优化 AGUI 协议处理器的导入语句和事件处理逻辑：
- 将部分导入移至函数内部以减少不必要的依赖
- 简化条件表达式与方法调用
- 改进类型提示以增强代码可读性

Change-Id: I1f4b89fa0a0ceeed09bcf1e6bb03370dfd1547de
Signed-off-by: OhYee <oyohyee@oyohyee.com>

* fix(agui_protocol): import run event classes directly

the runstartedevent and runfinishedevent classes are now imported directly from ag_ui.core to ensure proper event handling in the sse stream.

these events are essential for signaling the start and completion of runs within the agui protocol, improving reliability and maintainability of the streaming mechanism.

修复了 agui 协议中运行事件类的导入问题，确保 SSE 流能够正确处理运行开始和结束事件。此举增强了流机制的可靠性和可维护性。

Change-Id: Ied78843c9533c640a4706b379c8bd9109acc3b0b
Signed-off-by: OhYee <oyohyee@oyohyee.com>

* refactor(core): implement lazy loading for server module to handle optional dependencies

This change introduces a lazy loading mechanism for the server module to avoid import errors when optional dependencies are not installed. The server-related exports are now imported on-demand through __getattr__, with clear error messages when required optional dependencies are missing.

The implementation includes:
- TYPE_CHECKING import for type hints during development
- Delayed imports wrapped in TYPE_CHECKING blocks
- __getattr__ function to handle runtime imports
- Clear error messages directing users to install optional dependencies
- Server exports defined in _SERVER_EXPORTS set for tracking

This resolves issues where the package would fail to import when server optional dependencies were not available.

refactor(core): 实现服务器模块的延迟加载以处理可选依赖

此更改引入了服务器模块的延迟加载机制，以避免在未安装可选依赖项时出现导入错误。现在通过 __getattr__ 按需导入服务器相关导出，并在缺少必需的可选依赖项时提供清晰的错误消息。

实现包括：
- 用于开发期间类型提示的 TYPE_CHECKING 导入
- 包装在 TYPE_CHECKING 块中的延迟导入
- 用于处理运行时导入的 __getattr__ 函数
- 指向用户安装可选依赖项的清晰错误消息
- 定义在 _SERVER_EXPORTS 集合中用于跟踪的服务器导出

这解决了在服务器可选依赖项不可用时包导入失败的问题。

Change-Id: I9d8f7dd8e5c6d34dfd0619714ead5aea22105293
Signed-off-by: OhYee <oyohyee@oyohyee.com>

* refactor(core): use generic package mapping for optional dependency checks (#25)

* Initial plan

* fix(core): add 'ag_ui' to optional dependency error check

Add "ag_ui" to the error message checking logic in __getattr__ to properly
handle import errors when ag-ui-protocol is not installed. This ensures users
get helpful error messages when trying to use AGUIProtocolHandler or other
AG-UI related components without the server optional dependencies installed.

Addresses feedback from PR #23 review comment.

Co-authored-by: OhYee <13498329+OhYee@users.noreply.github.com>

* refactor(core): use generic package mapping for optional dependency checks

Refactor the import error handling to use a more maintainable and scalable
approach with a package mapping structure instead of hardcoded string checks.

Changes:
- Added _OPTIONAL_PACKAGES list with (import_name, install_name) tuples
- Refactored __getattr__ to iterate through the package mapping
- Now easier to add new optional dependencies in the future
- All three server optional dependencies (fastapi, uvicorn, ag_ui) registered

This makes the codebase more maintainable when adding new optional
dependencies in the future.

Addresses feedback from @OhYee on PR #23.

Co-authored-by: OhYee <13498329+OhYee@users.noreply.github.com>

* fix(core): restore specificity in error message and add clarifying comment

Address code review feedback:
- Restored "server" context in error message for better clarity
- Added comment clarifying that all entries are for server-related dependencies
- Maintains generic approach while preserving helpful context for users

This ensures users get clear, specific error messages while keeping the code
maintainable for future extensions.

Co-authored-by: OhYee <13498329+OhYee@users.noreply.github.com>

* refactor(core): use constant for server install command to reduce duplication

Extract the repeated install command string into a constant _SERVER_INSTALL_CMD
to make the code more maintainable and easier to update in the future.

This addresses code review feedback about reducing duplication in the package
mapping structure.

Co-authored-by: OhYee <13498329+OhYee@users.noreply.github.com>

* refactor(core): group packages by install command in _OPTIONAL_PACKAGES

Refactor _OPTIONAL_PACKAGES from a list of tuples to a dictionary that groups
packages by their installation command. This provides better organization when
multiple packages share the same installation command.

Changes:
- Changed from list of (package, install_cmd) tuples to dict of {install_cmd: [packages]}
- Removed _SERVER_INSTALL_CMD constant (now a dict key)
- Updated iteration logic to handle nested structure
- All three server packages (fastapi, uvicorn, ag_ui) grouped together

Benefits:
- Clearer relationship: install command -> packages it provides
- More compact when packages share the same install command
- Easier to see all packages for a given installation
- Scalable for future optional dependency groups

Addresses feedback from @OhYee about merging packages with the same command.

Co-authored-by: OhYee <13498329+OhYee@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: OhYee <13498329+OhYee@users.noreply.github.com>

---------

Signed-off-by: OhYee <oyohyee@oyohyee.com>
Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: OhYee <13498329+OhYee@users.noreply.github.com>

Author: OhYee

agentrun/__init__.py

@@ -16,6 +16,8 @@
 - Integration: 框架集成 / Framework integration
 """
 
+from typing import TYPE_CHECKING
+
 __version__ = "0.0.8"
 
 # Agent Runtime
@@ -87,27 +89,50 @@
     SandboxClient,
     Template,
 )
-# Server
-from agentrun.server import (
-    AgentRequest,
-    AgentResult,
-    AgentRunServer,
-    AsyncInvokeAgentHandler,
-    InvokeAgentHandler,
-    Message,
-    MessageRole,
-    OpenAIProtocolHandler,
-    ProtocolHandler,
-    SyncInvokeAgentHandler,
-)
 # ToolSet
 from agentrun.toolset import ToolSet, ToolSetClient
+from agentrun.utils.config import Config
 from agentrun.utils.exception import (
     ResourceAlreadyExistError,
     ResourceNotExistError,
 )
 from agentrun.utils.model import Status
 
+# Server - 延迟导入以避免可选依赖问题
+# Type hints for IDE and type checkers
+if TYPE_CHECKING:
+    from agentrun.server import (
+        AgentEvent,
+        AgentEventItem,
+        AgentRequest,
+        AgentResult,
+        AgentResultItem,
+        AgentReturnType,
+        AgentRunServer,
+        AguiEventNormalizer,
+        AGUIProtocolConfig,
+        AGUIProtocolHandler,
+        AsyncAgentEventGenerator,
+        AsyncAgentResultGenerator,
+        AsyncInvokeAgentHandler,
+        BaseProtocolHandler,
+        EventType,
+        InvokeAgentHandler,
+        MergeOptions,
+        Message,
+        MessageRole,
+        OpenAIProtocolConfig,
+        OpenAIProtocolHandler,
+        ProtocolConfig,
+        ProtocolHandler,
+        ServerConfig,
+        SyncAgentEventGenerator,
+        SyncAgentResultGenerator,
+        SyncInvokeAgentHandler,
+        Tool,
+        ToolCall,
+    )
+
 __all__ = [
     ######## Agent Runtime ########
     # base
@@ -185,22 +210,116 @@
     ######## ToolSet ########
     "ToolSetClient",
     "ToolSet",
-    ######## Server ########
+    ######## Server (延迟加载) ########
+    # Server
     "AgentRunServer",
+    # Config
+    "ServerConfig",
+    "ProtocolConfig",
+    "OpenAIProtocolConfig",
+    "AGUIProtocolConfig",
+    # Request/Response Models
     "AgentRequest",
-    "AgentResponse",
+    "AgentEvent",
     "AgentResult",
-    "AgentStreamResponse",
+    "Message",
+    "MessageRole",
+    "Tool",
+    "ToolCall",
+    # Event Types
+    "EventType",
+    # Type Aliases
+    "AgentEventItem",
+    "AgentResultItem",
+    "AgentReturnType",
+    "SyncAgentEventGenerator",
+    "SyncAgentResultGenerator",
+    "AsyncAgentEventGenerator",
+    "AsyncAgentResultGenerator",
     "InvokeAgentHandler",
     "AsyncInvokeAgentHandler",
     "SyncInvokeAgentHandler",
-    "Message",
-    "MessageRole",
+    # Protocol Base
     "ProtocolHandler",
+    "BaseProtocolHandler",
+    # Protocol - OpenAI
     "OpenAIProtocolHandler",
-    "AgentStreamIterator",
+    # Protocol - AG-UI
+    "AGUIProtocolHandler",
+    # Event Normalizer
+    "AguiEventNormalizer",
+    # Helpers
+    "MergeOptions",
     ######## Others ########
-    "Status",
     "ResourceNotExistError",
     "ResourceAlreadyExistError",
+    "Config",
 ]
+
+# Server 模块的所有导出
+_SERVER_EXPORTS = {
+    "AgentRunServer",
+    "ServerConfig",
+    "ProtocolConfig",
+    "OpenAIProtocolConfig",
+    "AGUIProtocolConfig",
+    "AgentRequest",
+    "AgentEvent",
+    "AgentResult",
+    "Message",
+    "MessageRole",
+    "Tool",
+    "ToolCall",
+    "EventType",
+    "AgentEventItem",
+    "AgentResultItem",
+    "AgentReturnType",
+    "SyncAgentEventGenerator",
+    "SyncAgentResultGenerator",
+    "AsyncAgentEventGenerator",
+    "AsyncAgentResultGenerator",
+    "InvokeAgentHandler",
+    "AsyncInvokeAgentHandler",
+    "SyncInvokeAgentHandler",
+    "ProtocolHandler",
+    "BaseProtocolHandler",
+    "OpenAIProtocolHandler",
+    "AGUIProtocolHandler",
+    "AguiEventNormalizer",
+    "MergeOptions",
+}
+
+# 可选依赖包映射：安装命令 -> 导入错误的包名列表
+# Optional dependency mapping: installation command -> list of import error package names
+# 将使用相同安装命令的包合并到一起 / Group packages with the same installation command
+_OPTIONAL_PACKAGES = {
+    "agentrun-sdk[server]": ["fastapi", "uvicorn", "ag_ui"],
+}
+
+
+def __getattr__(name: str):
+    """延迟加载 server 模块的导出，避免可选依赖导致导入失败
+
+    当用户访问 server 相关的类时，才尝试导入 server 模块。
+    如果 server 可选依赖未安装，会抛出清晰的错误提示。
+    """
+    if name in _SERVER_EXPORTS:
+        try:
+            from agentrun import server
+
+            return getattr(server, name)
+        except ImportError as e:
+            # 检查是否是缺少可选依赖导致的错误
+            error_str = str(e)
+            for install_cmd, package_names in _OPTIONAL_PACKAGES.items():
+                for package_name in package_names:
+                    if package_name in error_str:
+                        raise ImportError(
+                            f"'{name}' requires the 'server' optional dependencies. "
+                            f"Install with: pip install {install_cmd}\n"
+                            f"Original error: {e}"
+                        ) from e
+            # 其他导入错误继续抛出
+            raise
+
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

agentrun/credential/model.py

@@ -134,7 +134,7 @@ def outbound_tool_ak_sk(
         cls,
         provider: str,
         access_key_id: str,
-        access_key_secred: str,
+        access_key_secret: str,
         account_id: str,
     ):
         """配置访问第三方工具的 ak/sk 凭证"""
@@ -148,7 +148,7 @@ def outbound_tool_ak_sk(
                     "accountId": account_id,
                 },
             },
-            credential_secret=access_key_secred,
+            credential_secret=access_key_secret,
         )
 
     @classmethod

agentrun/model/model.py

@@ -131,6 +131,7 @@ class ProxyConfigTokenRateLimiter(BaseModel):
 
 class ProxyConfigAIGuardrailConfig(BaseModel):
     """AI 防护配置"""
+
     check_request: Optional[bool] = None
     check_response: Optional[bool] = None
 

agentrun/server/agui_protocol.py

@@ -19,36 +19,12 @@
 )
 import uuid
 
-from ag_ui.core import AssistantMessage
-from ag_ui.core import CustomEvent as AguiCustomEvent
-from ag_ui.core import EventType as AguiEventType
-from ag_ui.core import Message as AguiMessage
-from ag_ui.core import MessagesSnapshotEvent
-from ag_ui.core import RawEvent as AguiRawEvent
-from ag_ui.core import (
-    RunErrorEvent,
-    RunFinishedEvent,
-    RunStartedEvent,
-    StateDeltaEvent,
-    StateSnapshotEvent,
-    StepFinishedEvent,
-    StepStartedEvent,
-    SystemMessage,
-    TextMessageContentEvent,
-    TextMessageEndEvent,
-    TextMessageStartEvent,
-)
-from ag_ui.core import Tool as AguiTool
-from ag_ui.core import ToolCall as AguiToolCall
-from ag_ui.core import (
-    ToolCallArgsEvent,
-    ToolCallEndEvent,
-    ToolCallResultEvent,
-    ToolCallStartEvent,
-)
-from ag_ui.core import ToolMessage as AguiToolMessage
-from ag_ui.core import UserMessage
-from ag_ui.encoder import EventEncoder
+if TYPE_CHECKING:
+    from ag_ui.core import (
+        Message as AguiMessage,
+    )
+    from ag_ui.encoder import EventEncoder
+
 from fastapi import APIRouter, Request
 from fastapi.responses import StreamingResponse
 import pydash
@@ -101,16 +77,20 @@ class StreamStateMachine:
     run_errored: bool = False
 
     def end_all_tools(
-        self, encoder: EventEncoder, exclude: Optional[str] = None
+        self, encoder: "EventEncoder", exclude: Optional[str] = None
     ) -> Iterator[str]:
+        from ag_ui.core import ToolCallEndEvent
+
         for tool_id, state in self.tool_call_states.items():
             if exclude and tool_id == exclude:
                 continue
             if state.started and not state.ended:
                 yield encoder.encode(ToolCallEndEvent(tool_call_id=tool_id))
                 state.ended = True
 
-    def ensure_text_started(self, encoder: EventEncoder) -> Iterator[str]:
+    def ensure_text_started(self, encoder: "EventEncoder") -> Iterator[str]:
+        from ag_ui.core import TextMessageStartEvent
+
         if not self.text.started or self.text.ended:
             if self.text.ended:
                 self.text = TextState()
@@ -123,7 +103,9 @@ def ensure_text_started(self, encoder: EventEncoder) -> Iterator[str]:
             self.text.started = True
             self.text.ended = False
 
-    def end_text_if_open(self, encoder: EventEncoder) -> Iterator[str]:
+    def end_text_if_open(self, encoder: "EventEncoder") -> Iterator[str]:
+        from ag_ui.core import TextMessageEndEvent
+
         if self.text.started and not self.text.ended:
             yield encoder.encode(
                 TextMessageEndEvent(message_id=self.text.message_id)
@@ -168,6 +150,8 @@ class AGUIProtocolHandler(BaseProtocolHandler):
     name = "ag-ui"
 
     def __init__(self, config: Optional[ServerConfig] = None):
+        from ag_ui.encoder import EventEncoder
+
         self._config = config.agui if config else None
         self._encoder = EventEncoder()
 
@@ -363,6 +347,8 @@ async def _format_stream(
         Yields:
             SSE 格式的字符串
         """
+        from ag_ui.core import RunFinishedEvent, RunStartedEvent
+
         state = StreamStateMachine()
 
         # 发送 RUN_STARTED
@@ -420,6 +406,18 @@ def _process_event_with_boundaries(
         """处理事件并注入边界事件"""
         import json
 
+        from ag_ui.core import CustomEvent as AguiCustomEvent
+        from ag_ui.core import (
+            RunErrorEvent,
+            StateDeltaEvent,
+            StateSnapshotEvent,
+            TextMessageContentEvent,
+            ToolCallArgsEvent,
+            ToolCallEndEvent,
+            ToolCallResultEvent,
+            ToolCallStartEvent,
+        )
+
         # RAW 事件直接透传
         if event.event == EventType.RAW:
             raw_data = event.data.get("raw", "")
@@ -703,7 +701,7 @@ def _process_event_with_boundaries(
 
     def _convert_messages_for_snapshot(
         self, messages: List[Dict[str, Any]]
-    ) -> List[AguiMessage]:
+    ) -> List["AguiMessage"]:
         """将消息列表转换为 ag-ui-protocol 格式
 
         Args:
@@ -712,6 +710,10 @@ def _convert_messages_for_snapshot(
         Returns:
             ag-ui-protocol 消息列表
         """
+        from ag_ui.core import AssistantMessage, SystemMessage
+        from ag_ui.core import ToolMessage as AguiToolMessage
+        from ag_ui.core import UserMessage
+
         result = []
         for msg in messages:
             if not isinstance(msg, dict):
@@ -779,6 +781,8 @@ async def _error_stream(self, message: str) -> AsyncIterator[str]:
         Yields:
             SSE 格式的错误事件
         """
+        from ag_ui.core import RunErrorEvent, RunStartedEvent
+
         thread_id = str(uuid.uuid4())
         run_id = str(uuid.uuid4())