agentrun-sdk 0.0.4__py3-none-any.whl

agentrun/sandbox/template.py

@@ -0,0 +1,215 @@
+"""
+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_name: Optional[str] = None
+    """模板名称"""
+    template_version: Optional[str] = None
+    """模板版本"""
+    template_arn: Optional[str] = None
+    """模板 ARN"""
+    resource_name: Optional[str] = None
+    """资源名称"""
+    template_type: Optional[TemplateType] = None
+    """模板类型"""
+    cpu: Optional[float] = None
+    """CPU 核数"""
+    memory: Optional[int] = None
+    """内存大小（MB）"""
+    disk_size: Optional[int] = None
+    """磁盘大小（GB）"""
+    description: Optional[str] = None
+    """描述"""
+    execution_role_arn: Optional[str] = None
+    """执行角色 ARN"""
+    sandbox_idle_timeout_in_seconds: Optional[int] = None
+    """沙箱空闲超时时间（秒）"""
+    sandbox_ttlin_seconds: Optional[int] = None
+    """沙箱存活时间（秒）"""
+    share_concurrency_limit_per_sandbox: Optional[int] = None
+    """每个沙箱的最大并发会话数"""
+    template_configuration: Optional[Dict] = None
+    """模板配置"""
+    environment_variables: Optional[Dict] = None
+    """环境变量"""
+    network_configuration: Optional[TemplateNetworkConfiguration] = None
+    """网络配置"""
+    oss_configuration: Optional[List[TemplateOssConfiguration]] = None
+    """OSS 配置列表"""
+    log_configuration: Optional[TemplateLogConfiguration] = None
+    """日志配置"""
+    credential_configuration: Optional[TemplateCredentialConfiguration] = None
+    """凭证配置"""
+    container_configuration: Optional[TemplateContainerConfiguration] = None
+    """容器配置"""
+    mcp_options: Optional[TemplateMcpOptions] = None
+    """MCP 选项"""
+    mcp_state: Optional[TemplateMcpState] = None
+    """MCP 状态"""
+    created_at: Optional[str] = None
+    """创建时间"""
+    last_updated_at: Optional[str] = None
+    """最后更新时间"""
+    status: Optional[str] = None
+    """状态"""
+    status_reason: Optional[str] = None
+    """状态原因"""
+
+    @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,82 @@
+"""AgentRun Server 模块 / AgentRun Server Module
+
+提供 HTTP Server 集成能力,支持符合 AgentRun 规范的 Agent 调用接口。
+
+Example (基本使用):
+>>> from agentrun.server import AgentRunServer, AgentRequest, AgentResponse
+>>>
+>>> def invoke_agent(request: AgentRequest) -> AgentResponse:
+...     # 实现你的 Agent 逻辑
+...     return AgentResponse(...)
+>>>
+>>> server = AgentRunServer(invoke_agent=invoke_agent)
+>>> server.start(host="0.0.0.0", port=8080)
+
+Example (异步处理):
+>>> async def invoke_agent(request: AgentRequest) -> AgentResponse:
+...     # 异步实现你的 Agent 逻辑
+...     return AgentResponse(...)
+>>>
+>>> server = AgentRunServer(invoke_agent=invoke_agent)
+>>> server.start()
+
+Example (流式响应):
+>>> async def invoke_agent(request: AgentRequest):
+...     if request.stream:
+...         async def stream():
+...             for chunk in generate_chunks():
+...                 yield AgentStreamResponse(...)
+...         return stream()
+...     return AgentResponse(...)"""
+
+from .model import (
+    AgentRequest,
+    AgentResponse,
+    AgentResponseChoice,
+    AgentResponseUsage,
+    AgentResult,
+    AgentRunResult,
+    AgentStreamIterator,
+    AgentStreamResponse,
+    AgentStreamResponseChoice,
+    AgentStreamResponseDelta,
+    Message,
+    MessageRole,
+    Tool,
+    ToolCall,
+)
+from .openai_protocol import OpenAIProtocolHandler
+from .protocol import (
+    AsyncInvokeAgentHandler,
+    InvokeAgentHandler,
+    ProtocolHandler,
+    SyncInvokeAgentHandler,
+)
+from .server import AgentRunServer
+
+__all__ = [
+    # Server
+    "AgentRunServer",
+    # Request/Response Models
+    "AgentRequest",
+    "AgentResponse",
+    "AgentResponseChoice",
+    "AgentResponseUsage",
+    "AgentRunResult",
+    "AgentStreamResponse",
+    "AgentStreamResponseChoice",
+    "AgentStreamResponseDelta",
+    "Message",
+    "MessageRole",
+    "Tool",
+    "ToolCall",
+    # Type Aliases
+    "AgentResult",
+    "AgentStreamIterator",
+    "InvokeAgentHandler",
+    "AsyncInvokeAgentHandler",
+    "SyncInvokeAgentHandler",
+    # Protocol
+    "ProtocolHandler",
+    "OpenAIProtocolHandler",
+]

agentrun/server/invoker.py

@@ -0,0 +1,131 @@
+"""Agent 调用器 / Agent Invoker
+
+负责处理 Agent 调用的通用逻辑。
+Handles common logic for agent invocations.
+"""
+
+import asyncio
+import inspect
+from typing import cast
+
+from .model import AgentRequest, AgentResult, AgentRunResult
+from .protocol import (
+    AsyncInvokeAgentHandler,
+    InvokeAgentHandler,
+    SyncInvokeAgentHandler,
+)
+
+
+class AgentInvoker:
+    """Agent 调用器
+
+    职责:
+    1. 调用用户的 invoke_agent
+    2. 处理同步/异步调用
+    3. 自动转换 string/string迭代器为 AgentRunResult
+    4. 错误处理
+
+    Example:
+        >>> def my_agent(request: AgentRequest) -> str:
+        ...     return "Hello"  # 自动转换为 AgentRunResult
+        >>>
+        >>> invoker = AgentInvoker(my_agent)
+        >>> result = await invoker.invoke(AgentRequest(...))
+        >>> # result 是 AgentRunResult 对象
+    """
+
+    def __init__(self, invoke_agent: InvokeAgentHandler):
+        """初始化 Agent 调用器
+
+        Args:
+            invoke_agent: Agent 处理函数,可以是同步或异步
+        """
+        self.invoke_agent = invoke_agent
+        self.is_async = inspect.iscoroutinefunction(invoke_agent)
+
+    async def invoke(self, request: AgentRequest) -> AgentResult:
+        """调用 Agent 并返回结果
+
+        自动处理各种返回类型:
+        - string 或 string 迭代器 -> 转换为 AgentRunResult
+        - AgentRunResult -> 直接返回
+        - AgentResponse/ModelResponse -> 直接返回
+
+        Args:
+            request: AgentRequest 请求对象
+
+        Returns:
+            AgentResult: Agent 返回的结果
+
+        Raises:
+            Exception: Agent 执行中的任何异常
+        """
+        if self.is_async:
+            # 异步 handler
+            async_handler = cast(AsyncInvokeAgentHandler, self.invoke_agent)
+            result = await async_handler(request)
+        else:
+            # 同步 handler: 在线程池中运行,避免阻塞事件循环
+            sync_handler = cast(SyncInvokeAgentHandler, self.invoke_agent)
+            result = await asyncio.get_event_loop().run_in_executor(
+                None, sync_handler, request
+            )
+
+        # 自动转换 string 或 string 迭代器为 AgentRunResult
+        result = self._normalize_result(result)
+
+        return result
+
+    def _normalize_result(self, result: AgentResult) -> AgentResult:
+        """标准化返回结果
+
+        将 string 或 string 迭代器自动转换为 AgentRunResult。
+
+        Args:
+            result: 原始返回结果
+
+        Returns:
+            AgentResult: 标准化后的结果
+        """
+        # 如果是字符串,转换为 AgentRunResult
+        if isinstance(result, str):
+            return AgentRunResult(content=result)
+
+        # 如果是迭代器,检查是否是字符串迭代器
+        if self._is_string_iterator(result):
+            return AgentRunResult(content=result)  # type: ignore
+
+        # 其他类型直接返回
+        return result
+
+    def _is_string_iterator(self, obj) -> bool:
+        """检查是否是字符串迭代器
+
+        通过类型注解或启发式方法判断。
+
+        Args:
+            obj: 要检查的对象
+
+        Returns:
+            bool: 是否是字符串迭代器
+        """
+        # 排除已知的复杂类型
+        from .model import AgentResponse, AgentRunResult
+
+        if isinstance(obj, (AgentResponse, AgentRunResult, str, dict)):
+            return False
+
+        # 检查是否是迭代器
+        is_iterator = (
+            hasattr(obj, "__iter__") and not isinstance(obj, (str, bytes, dict))
+        ) or hasattr(obj, "__aiter__")
+
+        if not is_iterator:
+            return False
+
+        # 启发式判断: 如果没有 choices 属性,很可能是字符串迭代器
+        # (AgentResponse/ModelResponse 都有 choices 属性)
+        if hasattr(obj, "choices") or hasattr(obj, "model"):
+            return False
+
+        return True

agentrun/server/model.py

@@ -0,0 +1,225 @@
+"""AgentRun Server 模型定义 / AgentRun Server 模型Defines
+
+定义 invokeAgent callback 的参数结构和响应类型"""
+
+from enum import Enum
+from typing import (
+    Any,
+    AsyncIterator,
+    Dict,
+    Iterator,
+    List,
+    Optional,
+    TYPE_CHECKING,
+    Union,
+)
+
+from pydantic import BaseModel, Field
+
+if TYPE_CHECKING:
+    # 运行时不导入,避免依赖问题
+    from litellm.litellm_core_utils.streaming_handler import CustomStreamWrapper
+    from litellm.types.utils import ModelResponse
+
+
+class MessageRole(str, Enum):
+    """消息角色"""
+
+    SYSTEM = "system"
+    USER = "user"
+    ASSISTANT = "assistant"
+    TOOL = "tool"
+
+
+class Message(BaseModel):
+    """消息体"""
+
+    role: MessageRole
+    content: Optional[str] = None
+    name: Optional[str] = None
+    tool_calls: Optional[List[Dict[str, Any]]] = None
+    tool_call_id: Optional[str] = None
+
+
+class ToolCall(BaseModel):
+    """工具调用"""
+
+    id: str
+    type: str = "function"
+    function: Dict[str, Any]
+
+
+class Tool(BaseModel):
+    """工具定义 / 工具Defines"""
+
+    type: str = "function"
+    function: Dict[str, Any]
+
+
+class AgentRequest(BaseModel):
+    """Agent 请求参数
+
+    invokeAgent callback 接收的参数结构
+    符合 OpenAI Completions API 格式
+    """
+
+    # 必需参数
+    messages: List[Message] = Field(..., description="对话历史消息列表")
+
+    # 可选参数
+    model: Optional[str] = Field(None, description="模型名称")
+    stream: bool = Field(False, description="是否使用流式输出")
+    temperature: Optional[float] = Field(
+        None, description="采样温度", ge=0.0, le=2.0
+    )
+    top_p: Optional[float] = Field(
+        None, description="核采样参数", ge=0.0, le=1.0
+    )
+    max_tokens: Optional[int] = Field(
+        None, description="最大生成 token 数", gt=0
+    )
+    tools: Optional[List[Tool]] = Field(None, description="可用的工具列表")
+    tool_choice: Optional[Union[str, Dict[str, Any]]] = Field(
+        None, description="工具选择策略"
+    )
+    user: Optional[str] = Field(None, description="用户标识")
+
+    # 扩展参数
+    extra: Dict[str, Any] = Field(
+        default_factory=dict, description="其他自定义参数"
+    )
+
+
+class AgentResponseChoice(BaseModel):
+    """响应选项"""
+
+    index: int
+    message: Message
+    finish_reason: Optional[str] = None
+
+
+class AgentResponseUsage(BaseModel):
+    """Token 使用统计"""
+
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+
+
+class AgentRunResult(BaseModel):
+    """Agent 运行结果
+
+    核心数据结构,用于表示 Agent 执行结果。
+    content 字段支持字符串或字符串迭代器。
+
+    Example:
+        >>> # 返回字符串
+        >>> AgentRunResult(content="Hello, world!")
+        >>>
+        >>> # 返回字符串迭代器(流式)
+        >>> def stream():
+        ...     yield "Hello, "
+        ...     yield "world!"
+        >>> AgentRunResult(content=stream())
+    """
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    content: Union[str, Iterator[str], AsyncIterator[str], Any]
+    """响应内容,支持字符串或字符串迭代器 / 响应内容,Supports字符串或字符串迭代器"""
+
+
+class AgentResponse(BaseModel):
+    """Agent 响应(非流式)
+
+    灵活的响应数据结构,所有字段都是可选的。
+    用户可以只填充需要的字段,协议层会根据实际协议格式补充或跳过字段。
+
+    Example:
+        >>> # 最简单 - 只返回内容
+        >>> AgentResponse(content="Hello")
+        >>>
+        >>> # OpenAI 格式 - 完整字段
+        >>> AgentResponse(
+        ...     id="chatcmpl-123",
+        ...     model="gpt-4",
+        ...     choices=[...]
+        ... )
+    """
+
+    # 核心字段 - 协议无关
+    content: Optional[str] = None
+    """响应内容"""
+
+    # OpenAI 协议字段 - 可选
+    id: Optional[str] = Field(None, description="响应 ID")
+    object: Optional[str] = Field(None, description="对象类型")
+    created: Optional[int] = Field(None, description="创建时间戳")
+    model: Optional[str] = Field(None, description="使用的模型")
+    choices: Optional[List[AgentResponseChoice]] = Field(
+        None, description="响应选项列表"
+    )
+    usage: Optional[AgentResponseUsage] = Field(
+        None, description="Token 使用情况"
+    )
+
+    # 扩展字段 - 其他协议可能需要
+    extra: Dict[str, Any] = Field(
+        default_factory=dict, description="协议特定的额外字段"
+    )
+
+
+class AgentStreamResponseDelta(BaseModel):
+    """流式响应增量"""
+
+    role: Optional[MessageRole] = None
+    content: Optional[str] = None
+    tool_calls: Optional[List[Dict[str, Any]]] = None
+
+
+class AgentStreamResponse(BaseModel):
+    """流式响应块"""
+
+    id: Optional[str] = None
+    object: Optional[str] = None
+    created: Optional[int] = None
+    model: Optional[str] = None
+    choices: Optional[List["AgentStreamResponseChoice"]] = None
+    extra: Dict[str, Any] = Field(default_factory=dict)
+
+
+class AgentStreamResponseChoice(BaseModel):
+    """流式响应选项"""
+
+    index: int
+    delta: AgentStreamResponseDelta
+    finish_reason: Optional[str] = None
+
+
+# 类型别名 - 流式响应迭代器
+AgentStreamIterator = Union[
+    Iterator[AgentResponse],
+    AsyncIterator[AgentResponse],
+]
+
+# Model Service 类型 - 直接返回 litellm 的 ModelResponse
+if TYPE_CHECKING:
+    ModelServiceResult = Union["ModelResponse", "CustomStreamWrapper"]
+else:
+    ModelServiceResult = Any  # 运行时使用 Any
+
+# AgentResult - 支持多种返回形式
+# 用户可以返回:
+# 1. string 或 string 迭代器 - 自动转换为 AgentRunResult
+# 2. AgentRunResult - 核心数据结构
+# 3. AgentResponse - 完整响应对象
+# 4. ModelResponse - Model Service 响应
+AgentResult = Union[
+    str,  # 简化: 直接返回字符串
+    Iterator[str],  # 简化: 字符串流
+    AsyncIterator[str],  # 简化: 异步字符串流
+    AgentRunResult,  # 核心: AgentRunResult 对象
+    AgentResponse,  # 完整: AgentResponse 对象
+    AgentStreamIterator,  # 流式: AgentResponse 流
+    ModelServiceResult,  # Model Service: ModelResponse 或 CustomStreamWrapper
+]