Merge pull request #17 from Serverless-Devs/agentrun-agui

feat(server): 实现 AG-UI 协议和生命周期钩子系统

Author: OhYee

AGENTS.md

@@ -380,8 +380,34 @@ async def deploy_multiple_agents():
 
 # 运行
 agents = asyncio.run(deploy_multiple_agents())
+
+### 8. 变更后的类型检查要求
+
+所有由 AI（或自动化 agent）提交或修改的代码变更，必须在提交/合并前后执行静态类型检查，并在变更记录中包含检查结果摘要：
+
+- **运行命令**：使用项目根目录的 mypy 配置运行：
+
+    ```bash
+    mypy --config-file mypy.ini .
+    ```
+
+- **必需项**：AI 在每次修改代码并准备提交时，必须：
+    - 运行上述类型检查命令并等待完成；
+    - 若检查通过，在提交消息或 PR 描述中写入简短摘要（例如："类型检查通过，检查文件数 N"）；
+    - 若检查失败，AI 应在 PR 描述中列出前 30 条错误（或最关键的若干条），并给出优先修复建议或自动修复方案。
+
+- **CI 行为**：项目 CI 可根据仓库策略决定是否将类型检查失败作为阻断条件；AI 应遵从仓库当前 CI 策略并在 PR 中说明检查结果。
+
+此要求旨在保证类型安全随代码变更持续得到验证，减少回归并提高编辑器与 Copilot 的诊断可靠性。
 ```
 
+### 9. 运行命令约定
+
+请使用 `uv run ...` 执行所有 Python 相关命令，避免直接调用系统的 `python`。例如：
+
+- `uv run mypy --config-file mypy.ini .`
+- `uv run python examples/quick_start.py`
+
 ## 常见问题
 
 ### Q: Agent Runtime 启动失败怎么办？

agentrun/__init__.py

@@ -90,11 +90,8 @@
 # Server
 from agentrun.server import (
     AgentRequest,
-    AgentResponse,
     AgentResult,
     AgentRunServer,
-    AgentStreamIterator,
-    AgentStreamResponse,
     AsyncInvokeAgentHandler,
     InvokeAgentHandler,
     Message,

agentrun/integration/langchain/__init__.py

@@ -1,8 +1,29 @@
-"""LangChain 集成模块,提供 AgentRun 模型与沙箱的 LangChain 适配。 / LangChain 集成 Module"""
+"""LangChain 集成模块
+
+使用 AgentRunConverter 将 LangChain 事件转换为 AG-UI 协议事件：
+
+    >>> from agentrun.integration.langchain import AgentRunConverter
+    >>>
+    >>> async def invoke_agent(request: AgentRequest):
+    ...     converter = AgentRunConverter()
+    ...     async for event in agent.astream_events(input_data, version="v2"):
+    ...         for item in converter.convert(event):
+    ...             yield item
+
+支持多种调用方式：
+- agent.astream_events(input, version="v2") - 支持 token by token
+- agent.stream(input, stream_mode="updates") - 按节点输出
+- agent.astream(input, stream_mode="updates") - 异步按节点输出
+"""
+
+from agentrun.integration.langgraph.agent_converter import (
+    AgentRunConverter,
+)  # 向后兼容
 
 from .builtin import model, sandbox_toolset, toolset
 
 __all__ = [
+    "AgentRunConverter",
     "model",
     "toolset",
     "sandbox_toolset",

agentrun/integration/langchain/model_adapter.py

@@ -23,7 +23,6 @@ def __init__(self):
 
     def wrap_model(self, common_model: Any) -> Any:
         """包装 CommonModel 为 LangChain BaseChatModel / LangChain Model Adapter"""
-        from httpx import AsyncClient
         from langchain_openai import ChatOpenAI
 
         info = common_model.get_model_info()  # 确保模型可用
@@ -32,6 +31,7 @@ def wrap_model(self, common_model: Any) -> Any:
             api_key=info.api_key,
             model=info.model,
             base_url=info.base_url,
-            async_client=AsyncClient(headers=info.headers),
+            default_headers=info.headers,
             stream_usage=True,
+            streaming=True,  # 启用流式输出以支持 token by token
         )

agentrun/integration/langgraph/__init__.py

@@ -1,12 +1,34 @@
-"""LangGraph 集成模块。 / LangGraph 集成 Module
+"""LangGraph 集成模块
 
-提供 AgentRun 模型与沙箱工具的 LangGraph 适配入口。 / 提供 AgentRun 模型with沙箱工具的 LangGraph 适配入口。
-LangGraph 与 LangChain 兼容，因此直接复用 LangChain 的转换逻辑。 / LangGraph with LangChain 兼容，因此直接复用 LangChain 的转换逻辑。
+使用 AgentRunConverter 将 LangGraph 事件转换为 AG-UI 协议事件：
+
+    >>> from agentrun.integration.langgraph import AgentRunConverter
+    >>>
+    >>> async def invoke_agent(request: AgentRequest):
+    ...     converter = AgentRunConverter()
+    ...     async for event in agent.astream_events(input_data, version="v2"):
+    ...         for item in converter.convert(event):
+    ...             yield item
+
+或使用静态方法（无状态）：
+
+    >>> from agentrun.integration.langgraph import AgentRunConverter
+    >>>
+    >>> async for event in agent.astream_events(input_data, version="v2"):
+    ...     for item in AgentRunConverter.to_agui_events(event):
+    ...         yield item
+
+支持多种调用方式：
+- agent.astream_events(input, version="v2") - 支持 token by token
+- agent.stream(input, stream_mode="updates") - 按节点输出
+- agent.astream(input, stream_mode="updates") - 异步按节点输出
 """
 
+from .agent_converter import AgentRunConverter
 from .builtin import model, sandbox_toolset, toolset
 
 __all__ = [
+    "AgentRunConverter",
     "model",
     "toolset",
     "sandbox_toolset",