agentrun-inner-test 0.0.62__py3-none-any.whl

agentrun/sandbox/template.py

@@ -0,0 +1,217 @@
+"""
+This file is auto generated by the code generation script.
+Do not modify this file manually.
+Use the `make codegen` command to regenerate.
+
+当前文件为自动生成的控制 API 客户端代码。请勿手动修改此文件。
+使用 `make codegen` 命令重新生成。
+
+source: agentrun/sandbox/__template_async_template.py
+
+Template 高层 API / Template High-Level API
+
+此模块定义沙箱模板资源的高级API。
+This module defines the high-level API for sandbox template resources.
+"""
+
+from typing import Dict, List, Optional
+
+from agentrun.sandbox.model import (
+    PageableInput,
+    TemplateContainerConfiguration,
+    TemplateCredentialConfiguration,
+    TemplateInput,
+    TemplateLogConfiguration,
+    TemplateMcpOptions,
+    TemplateMcpState,
+    TemplateNetworkConfiguration,
+    TemplateOssConfiguration,
+    TemplateType,
+)
+from agentrun.utils.config import Config
+from agentrun.utils.model import BaseModel
+
+
+class Template(BaseModel):
+    """Template 实例
+
+    封装了 Template 的基本信息和操作方法
+    """
+
+    template_id: Optional[str] = None
+    """模板 ID / Template ID"""
+    template_name: Optional[str] = None
+    """模板名称 / Template Name"""
+    template_version: Optional[str] = None
+    """模板版本 / Template Version"""
+    template_arn: Optional[str] = None
+    """模板 ARN / Template ARN"""
+    resource_name: Optional[str] = None
+    """资源名称 / Resource Name"""
+    template_type: Optional[TemplateType] = None
+    """模板类型 / Template Type"""
+    cpu: Optional[float] = None
+    """CPU 核数 / CPU Cores"""
+    memory: Optional[int] = None
+    """内存大小（MB） / Memory Size (MB)"""
+    disk_size: Optional[int] = None
+    """磁盘大小（GB） / Disk Size (GB)"""
+    description: Optional[str] = None
+    """描述 / Description"""
+    execution_role_arn: Optional[str] = None
+    """执行角色 ARN / Execution Role ARN"""
+    sandbox_idle_timeout_in_seconds: Optional[int] = None
+    """沙箱空闲超时时间（秒） / Sandbox Idle Timeout (seconds)"""
+    sandbox_ttlin_seconds: Optional[int] = None
+    """沙箱存活时间（秒） / Sandbox TTL (seconds)"""
+    share_concurrency_limit_per_sandbox: Optional[int] = None
+    """每个沙箱的最大并发会话数 / Max Concurrency Limit Per Sandbox"""
+    template_configuration: Optional[Dict] = None
+    """模板配置 / Template Configuration"""
+    environment_variables: Optional[Dict] = None
+    """环境变量 / Environment Variables"""
+    network_configuration: Optional[TemplateNetworkConfiguration] = None
+    """网络配置 / Network Configuration"""
+    oss_configuration: Optional[List[TemplateOssConfiguration]] = None
+    """OSS 配置列表 / OSS Configuration List"""
+    log_configuration: Optional[TemplateLogConfiguration] = None
+    """日志配置 / Log Configuration"""
+    credential_configuration: Optional[TemplateCredentialConfiguration] = None
+    """凭证配置 / Credential Configuration"""
+    container_configuration: Optional[TemplateContainerConfiguration] = None
+    """容器配置 / Container Configuration"""
+    mcp_options: Optional[TemplateMcpOptions] = None
+    """MCP 选项 / MCP Options"""
+    mcp_state: Optional[TemplateMcpState] = None
+    """MCP 状态 / MCP State"""
+    allow_anonymous_manage: Optional[bool] = None
+    """是否允许匿名管理 / Whether to allow anonymous management"""
+    created_at: Optional[str] = None
+    """创建时间 / Creation Time"""
+    last_updated_at: Optional[str] = None
+    """最后更新时间 / Last Updated Time"""
+    status: Optional[str] = None
+    """状态 / Status"""
+    status_reason: Optional[str] = None
+    """状态原因 / Status Reason"""
+
+    @classmethod
+    def __get_client(cls, config: Optional[Config] = None):
+        """获取 Sandbox 客户端"""
+        from .client import SandboxClient
+
+        return SandboxClient(config)
+
+    @classmethod
+    async def create_async(
+        cls, input: TemplateInput, config: Optional[Config] = None
+    ):
+        return await cls.__get_client(config=config).create_template_async(
+            input, config=config
+        )
+
+    @classmethod
+    def create(cls, input: TemplateInput, config: Optional[Config] = None):
+        return cls.__get_client(config=config).create_template(
+            input, config=config
+        )
+
+    @classmethod
+    async def delete_by_name_async(
+        cls, template_name: str, config: Optional[Config] = None
+    ):
+        return await cls.__get_client(config=config).delete_template_async(
+            template_name=template_name, config=config
+        )
+
+    @classmethod
+    def delete_by_name(
+        cls, template_name: str, config: Optional[Config] = None
+    ):
+        return cls.__get_client(config=config).delete_template(
+            template_name=template_name, config=config
+        )
+
+    @classmethod
+    async def update_by_name_async(
+        cls,
+        template_name: str,
+        input: TemplateInput,
+        config: Optional[Config] = None,
+    ):
+        return await cls.__get_client(config=config).update_template_async(
+            template_name=template_name, input=input, config=config
+        )
+
+    @classmethod
+    def update_by_name(
+        cls,
+        template_name: str,
+        input: TemplateInput,
+        config: Optional[Config] = None,
+    ):
+        return cls.__get_client(config=config).update_template(
+            template_name=template_name, input=input, config=config
+        )
+
+    @classmethod
+    async def get_by_name_async(
+        cls, template_name: str, config: Optional[Config] = None
+    ):
+        return await cls.__get_client(config=config).get_template_async(
+            template_name=template_name, config=config
+        )
+
+    @classmethod
+    def get_by_name(cls, template_name: str, config: Optional[Config] = None):
+        return cls.__get_client(config=config).get_template(
+            template_name=template_name, config=config
+        )
+
+    @classmethod
+    async def list_templates_async(
+        cls,
+        input: Optional[PageableInput] = None,
+        config: Optional[Config] = None,
+    ):
+        return await cls.__get_client(config=config).list_templates_async(
+            input, config=config
+        )
+
+    @classmethod
+    def list_templates(
+        cls,
+        input: Optional[PageableInput] = None,
+        config: Optional[Config] = None,
+    ):
+        return cls.__get_client(config=config).list_templates(
+            input, config=config
+        )
+
+    async def create_sandbox_async(
+        self,
+        sandbox_idle_timeout_seconds: Optional[int] = None,
+        config: Optional[Config] = None,
+    ):
+        if self.template_name is None:
+            raise ValueError("Template name is required")
+
+        return await self.__get_client(config=config).create_sandbox_async(
+            self.template_name,
+            sandbox_idle_timeout_seconds=sandbox_idle_timeout_seconds,
+            config=config,
+        )
+
+    def create_sandbox(
+        self,
+        sandbox_idle_timeout_seconds: Optional[int] = None,
+        config: Optional[Config] = None,
+    ):
+        if self.template_name is None:
+            raise ValueError("Template name is required")
+
+        return self.__get_client(config=config).create_sandbox(
+            self.template_name,
+            sandbox_idle_timeout_seconds=sandbox_idle_timeout_seconds,
+            config=config,
+        )

agentrun/server/__init__.py

@@ -0,0 +1,191 @@
+"""AgentRun Server 模块 / AgentRun Server Module
+
+提供 HTTP Server 集成能力，支持符合 AgentRun 规范的 Agent 调用接口。
+支持 OpenAI Chat Completions 和 AG-UI 两种协议。
+
+Example (基本使用 - 返回字符串):
+>>> from agentrun.server import AgentRunServer, AgentRequest
+>>>
+>>> def invoke_agent(request: AgentRequest):
+...     return "Hello, world!"
+>>>
+>>> server = AgentRunServer(invoke_agent=invoke_agent)
+>>> server.start(port=9000)
+
+Example (流式输出):
+>>> def invoke_agent(request: AgentRequest):
+...     for word in ["Hello", ", ", "world", "!"]:
+...         yield word
+>>>
+>>> AgentRunServer(invoke_agent=invoke_agent).start()
+
+Example (使用事件):
+>>> from agentrun.server import AgentEvent, EventType
+>>>
+>>> async def invoke_agent(request: AgentRequest):
+...     # 发送自定义事件（如步骤开始）
+...     yield AgentEvent(
+...         event=EventType.CUSTOM,
+...         data={"name": "step_started", "value": {"step": "processing"}}
+...     )
+...
+...     # 流式输出内容
+...     yield "Hello, "
+...     yield "world!"
+...
+...     # 发送步骤结束事件
+...     yield AgentEvent(
+...         event=EventType.CUSTOM,
+...         data={"name": "step_finished", "value": {"step": "processing"}}
+...     )
+
+Example (工具调用事件):
+>>> async def invoke_agent(request: AgentRequest):
+...     # 完整工具调用
+...     yield AgentEvent(
+...         event=EventType.TOOL_CALL,
+...         data={"id": "call_1", "name": "get_time", "args": '{"timezone": "UTC"}'}
+...     )
+...
+...     # 执行工具
+...     result = "2024-01-01 12:00:00"
+...
+...     # 工具调用结果
+...     yield AgentEvent(
+...         event=EventType.TOOL_RESULT,
+...         data={"id": "call_1", "result": result}
+...     )
+...
+...     yield f"当前时间: {result}"
+
+Example (流式工具输出):
+>>> async def invoke_agent(request: AgentRequest):
+...     # 发起工具调用
+...     yield AgentEvent(
+...         event=EventType.TOOL_CALL,
+...         data={"id": "call_1", "name": "run_code", "args": '{"code": "..."}'}
+...     )
+...
+...     # 流式输出执行过程
+...     yield AgentEvent(
+...         event=EventType.TOOL_RESULT_CHUNK,
+...         data={"id": "call_1", "delta": "Step 1: Compiling...\\n"}
+...     )
+...     yield AgentEvent(
+...         event=EventType.TOOL_RESULT_CHUNK,
+...         data={"id": "call_1", "delta": "Step 2: Running...\\n"}
+...     )
+...
+...     # 最终结果（标识流式输出结束）
+...     yield AgentEvent(
+...         event=EventType.TOOL_RESULT,
+...         data={"id": "call_1", "result": "Execution completed."}
+...     )
+
+Example (HITL - 请求人类介入):
+>>> async def invoke_agent(request: AgentRequest):
+...     # 请求用户确认
+...     yield AgentEvent(
+...         event=EventType.HITL,
+...         data={
+...             "id": "hitl_1",
+...             "tool_call_id": "call_delete",  # 可选
+...             "type": "confirmation",
+...             "prompt": "确认删除文件?",
+...             "options": ["确认", "取消"]
+...         }
+...     )
+...     # 用户响应将通过下一轮对话的 messages 传回
+
+Example (访问原始请求):
+>>> async def invoke_agent(request: AgentRequest):
+...     # 访问当前协议
+...     protocol = request.protocol  # "openai" 或 "agui"
+...
+...     # 访问原始请求头
+...     auth = request.raw_request.headers.get("Authorization")
+...
+...     # 访问查询参数
+...     params = request.raw_request.query_params
+...
+...     # 访问客户端 IP
+...     client_ip = request.raw_request.client.host if request.raw_request.client else None
+...
+...     return "Hello, world!"
+"""
+
+from ..utils.helper import MergeOptions
+from .agui_normalizer import AguiEventNormalizer
+from .agui_protocol import AGUIProtocolHandler
+from .model import (
+    AgentEvent,
+    AgentEventItem,
+    AgentRequest,
+    AgentResult,
+    AgentResultItem,
+    AgentReturnType,
+    AGUIProtocolConfig,
+    AsyncAgentEventGenerator,
+    AsyncAgentResultGenerator,
+    EventType,
+    Message,
+    MessageRole,
+    OpenAIProtocolConfig,
+    ProtocolConfig,
+    ServerConfig,
+    SyncAgentEventGenerator,
+    SyncAgentResultGenerator,
+    Tool,
+    ToolCall,
+)
+from .openai_protocol import OpenAIProtocolHandler
+from .protocol import (
+    AsyncInvokeAgentHandler,
+    BaseProtocolHandler,
+    InvokeAgentHandler,
+    ProtocolHandler,
+    SyncInvokeAgentHandler,
+)
+from .server import AgentRunServer
+
+__all__ = [
+    # Server
+    "AgentRunServer",
+    # Config
+    "ServerConfig",
+    "ProtocolConfig",
+    "OpenAIProtocolConfig",
+    "AGUIProtocolConfig",
+    # Request/Response Models
+    "AgentRequest",
+    "AgentEvent",
+    "AgentResult",  # 兼容别名
+    "Message",
+    "MessageRole",
+    "Tool",
+    "ToolCall",
+    # Event Types
+    "EventType",
+    # Type Aliases
+    "AgentEventItem",
+    "AgentResultItem",  # 兼容别名
+    "AgentReturnType",
+    "SyncAgentEventGenerator",
+    "SyncAgentResultGenerator",  # 兼容别名
+    "AsyncAgentEventGenerator",
+    "AsyncAgentResultGenerator",  # 兼容别名
+    "InvokeAgentHandler",
+    "AsyncInvokeAgentHandler",
+    "SyncInvokeAgentHandler",
+    # Protocol Base
+    "ProtocolHandler",
+    "BaseProtocolHandler",
+    # Protocol - OpenAI
+    "OpenAIProtocolHandler",
+    # Protocol - AG-UI
+    "AGUIProtocolHandler",
+    # Event Normalizer
+    "AguiEventNormalizer",
+    # Helpers
+    "MergeOptions",
+]

agentrun/server/agui_normalizer.py

@@ -0,0 +1,180 @@
+"""AG-UI 事件规范化器
+
+提供事件流规范化功能，确保事件符合 AG-UI 协议的顺序要求。
+
+主要功能：
+- 追踪工具调用状态
+- 在 TOOL_RESULT 前确保工具调用已开始
+- 自动补充缺失的状态
+
+注意：边界事件（如 TEXT_MESSAGE_START/END、TOOL_CALL_START/END）
+由协议层（agui_protocol.py）自动生成，不需要用户关心。
+
+使用示例:
+
+    >>> from agentrun.server.agui_normalizer import AguiEventNormalizer
+    >>>
+    >>> normalizer = AguiEventNormalizer()
+    >>> for event in raw_events:
+    ...     for normalized_event in normalizer.normalize(event):
+    ...         yield normalized_event
+"""
+
+from typing import Any, Dict, Iterator, List, Optional, Set, Union
+
+from .model import AgentEvent, EventType
+
+
+class AguiEventNormalizer:
+    """AG-UI 事件规范化器
+
+    追踪工具调用状态，确保事件顺序正确：
+    1. 追踪已开始的工具调用
+    2. 确保 TOOL_RESULT 前工具调用存在
+
+    协议层会自动处理边界事件（START/END），这个类主要用于
+    高级用户需要手动控制事件流时。
+
+    Example:
+        >>> normalizer = AguiEventNormalizer()
+        >>> for event in agent_events:
+        ...     for normalized in normalizer.normalize(event):
+        ...         yield normalized
+    """
+
+    def __init__(self):
+        # 已看到的工具调用 ID 集合
+        self._seen_tool_calls: Set[str] = set()
+        # 活跃的工具调用信息（tool_call_id -> tool_call_name）
+        self._active_tool_calls: Dict[str, str] = {}
+
+    def normalize(
+        self,
+        event: Union[AgentEvent, str, Dict[str, Any]],
+    ) -> Iterator[AgentEvent]:
+        """规范化单个事件
+
+        将事件标准化为 AgentEvent，并追踪工具调用状态。
+
+        Args:
+            event: 原始事件（AgentEvent、str 或 dict）
+
+        Yields:
+            规范化后的事件
+        """
+        # 将事件标准化为 AgentEvent
+        normalized_event = self._to_agent_event(event)
+        if normalized_event is None:
+            return
+
+        # 根据事件类型进行处理
+        event_type = normalized_event.event
+
+        if event_type == EventType.TOOL_CALL_CHUNK:
+            yield from self._handle_tool_call_chunk(normalized_event)
+
+        elif event_type == EventType.TOOL_CALL:
+            yield from self._handle_tool_call(normalized_event)
+
+        elif event_type == EventType.TOOL_RESULT:
+            yield from self._handle_tool_result(normalized_event)
+
+        else:
+            # 其他事件类型直接传递
+            yield normalized_event
+
+    def _to_agent_event(
+        self, event: Union[AgentEvent, str, Dict[str, Any]]
+    ) -> Optional[AgentEvent]:
+        """将事件转换为 AgentEvent"""
+        if isinstance(event, AgentEvent):
+            return event
+
+        if isinstance(event, str):
+            # 字符串转为 TEXT
+            return AgentEvent(
+                event=EventType.TEXT,
+                data={"delta": event},
+            )
+
+        if isinstance(event, dict):
+            event_type = event.get("event")
+            if event_type is None:
+                return None
+
+            # 尝试解析 event_type
+            if isinstance(event_type, str):
+                try:
+                    event_type = EventType(event_type)
+                except ValueError:
+                    try:
+                        event_type = EventType[event_type]
+                    except KeyError:
+                        return None
+
+            return AgentEvent(
+                event=event_type,
+                data=event.get("data", {}),
+            )
+
+        return None
+
+    def _handle_tool_call(self, event: AgentEvent) -> Iterator[AgentEvent]:
+        """处理 TOOL_CALL 事件
+
+        记录工具调用并直接传递
+        """
+        tool_call_id = event.data.get("id", "")
+        tool_call_name = event.data.get("name", "")
+
+        if tool_call_id:
+            self._seen_tool_calls.add(tool_call_id)
+            self._active_tool_calls[tool_call_id] = tool_call_name
+
+        yield event
+
+    def _handle_tool_call_chunk(
+        self, event: AgentEvent
+    ) -> Iterator[AgentEvent]:
+        """处理 TOOL_CALL_CHUNK 事件
+
+        记录工具调用并直接传递
+        """
+        tool_call_id = event.data.get("id", "")
+        tool_call_name = event.data.get("name", "")
+
+        if tool_call_id:
+            self._seen_tool_calls.add(tool_call_id)
+            if tool_call_name:
+                self._active_tool_calls[tool_call_id] = tool_call_name
+
+        yield event
+
+    def _handle_tool_result(self, event: AgentEvent) -> Iterator[AgentEvent]:
+        """处理 TOOL_RESULT 事件
+
+        标记工具调用完成
+        """
+        tool_call_id = event.data.get("id", "")
+
+        if tool_call_id:
+            # 标记工具调用已完成（从活跃列表移除）
+            self._active_tool_calls.pop(tool_call_id, None)
+
+        yield event
+
+    def get_active_tool_calls(self) -> List[str]:
+        """获取当前活跃（未结束）的工具调用 ID 列表"""
+        return list(self._active_tool_calls.keys())
+
+    def get_seen_tool_calls(self) -> List[str]:
+        """获取所有已见过的工具调用 ID 列表"""
+        return list(self._seen_tool_calls)
+
+    def reset(self):
+        """重置状态
+
+        在处理新的请求时，建议创建新的实例而不是复用。
+        """
+        self._seen_tool_calls.clear()
+        self._active_tool_calls.clear()