agentrun-sdk 0.0.4__py3-none-any.whl

agentrun/server/protocol.py

@@ -0,0 +1,96 @@
+"""协议抽象层 / Protocol Abstraction Layer
+
+定义协议接口,支持未来扩展多种协议格式(OpenAI, Anthropic, Google 等)。
+Defines protocol interfaces, supporting future expansion of various protocol formats (OpenAI, Anthropic, Google, etc.).
+
+基于 Router 的设计 / Router-based design:
+- 每个协议提供自己的 FastAPI Router / Each protocol provides its own FastAPI Router
+- Server 负责挂载 Router 并管理路由前缀 / Server mounts Routers and manages route prefixes
+- 协议完全自治,无需向 Server 声明接口 / Protocols are fully autonomous, no need to declare interfaces to Server
+"""
+
+from abc import ABC, abstractmethod
+from typing import Awaitable, Callable, TYPE_CHECKING, Union
+
+from .model import AgentRequest, AgentResult
+
+if TYPE_CHECKING:
+    from fastapi import APIRouter
+
+    from .invoker import AgentInvoker
+
+
+class ProtocolHandler(ABC):
+    """协议处理器基类 / Protocol Handler Base Class
+
+    基于 Router 的设计 / Router-based design:
+    协议通过 as_fastapi_router() 方法提供完整的路由定义,包括所有端点、请求处理、响应格式化等。
+    Protocol provides complete route definitions through as_fastapi_router() method, including all endpoints, request handling, response formatting, etc.
+
+    Server 只需挂载 Router 并管理路由前缀,无需了解协议细节。
+    Server only needs to mount Router and manage route prefixes, without knowing protocol details.
+    """
+
+    @abstractmethod
+    def as_fastapi_router(self, agent_invoker: "AgentInvoker") -> "APIRouter":
+        """
+        将协议转换为 FastAPI Router
+
+        协议自己决定:
+        - 有哪些端点
+        - 端点的路径
+        - HTTP 方法
+        - 请求/响应处理
+
+        Args:
+            agent_invoker: Agent 调用器,用于执行用户的 invoke_agent
+
+        Returns:
+            APIRouter: FastAPI 路由器,包含该协议的所有端点
+
+        Example:
+            ```python
+            def as_fastapi_router(self, agent_invoker):
+                router = APIRouter()
+
+                @router.post("/chat/completions")
+                async def chat_completions(request: Request):
+                    data = await request.json()
+                    agent_request = parse_request(data)
+                    result = await agent_invoker.invoke(agent_request)
+                    return format_response(result)
+
+                return router
+            ```
+        """
+        pass
+
+    def get_prefix(self) -> str:
+        """
+        获取协议建议的路由前缀
+
+        Server 会优先使用用户指定的前缀,如果没有指定则使用此建议值。
+
+        Returns:
+            str: 建议的前缀,如 "/v1" 或 ""
+
+        Example:
+            - OpenAI 协议: "/v1"
+            - Anthropic 协议: "/anthropic"
+            - 无前缀: ""
+        """
+        return ""
+
+
+# Handler 类型定义
+# 同步 handler: 普通函数,直接返回 AgentResult
+SyncInvokeAgentHandler = Callable[[AgentRequest], AgentResult]
+
+# 异步 handler: 协程函数,返回 Awaitable[AgentResult]
+AsyncInvokeAgentHandler = Callable[[AgentRequest], Awaitable[AgentResult]]
+
+# 通用 handler: 可以是同步或异步
+InvokeAgentHandler = Union[
+    SyncInvokeAgentHandler,
+    AsyncInvokeAgentHandler,
+]

agentrun/server/server.py

@@ -0,0 +1,192 @@
+"""AgentRun HTTP Server / AgentRun HTTP 服务器
+
+基于 Router 的设计 / Router-based design:
+- 每个协议提供自己的 Router / Each protocol provides its own Router
+- Server 负责挂载 Router 并管理路由前缀 / Server mounts Routers and manages route prefixes
+- 支持多协议同时运行 / Supports running multiple protocols simultaneously
+"""
+
+from typing import Any, Dict, List, Optional
+
+from fastapi import FastAPI
+import uvicorn
+
+from agentrun.utils.log import logger
+
+from .invoker import AgentInvoker
+from .openai_protocol import OpenAIProtocolHandler
+from .protocol import InvokeAgentHandler, ProtocolHandler
+
+
+class AgentRunServer:
+    """AgentRun HTTP Server / AgentRun HTTP 服务器
+
+    基于 Router 的架构 / Router-based architecture:
+    - 每个协议提供完整的 FastAPI Router / Each protocol provides a complete FastAPI Router
+    - Server 只负责组装和前缀管理 / Server only handles assembly and prefix management
+    - 易于扩展新协议 / Easy to extend with new protocols
+
+    Example (默认 OpenAI 协议 / Default OpenAI protocol):
+        >>> def invoke_agent(request: AgentRequest):
+        ...     return "Hello, world!"
+        >>>
+        >>> server = AgentRunServer(invoke_agent=invoke_agent)
+        >>> server.start(port=8000)
+        # 可访问 / Accessible: POST http://localhost:8000/v1/chat/completions
+
+    Example (自定义前缀 / Custom prefix):
+        >>> server = AgentRunServer(
+        ...     invoke_agent=invoke_agent,
+        ...     prefix_overrides={"OpenAIProtocolHandler": "/api/v1"}
+        ... )
+        >>> server.start(port=8000)
+        # 可访问 / Accessible: POST http://localhost:8000/api/v1/chat/completions
+
+    Example (多协议 / Multiple protocols):
+        >>> server = AgentRunServer(
+        ...     invoke_agent=invoke_agent,
+        ...     protocols=[
+        ...         OpenAIProtocolHandler(),
+        ...         CustomProtocolHandler(),
+        ...     ]
+        ... )
+        >>> server.start(port=8000)
+
+    Example (集成到现有 FastAPI 应用 / Integrate with existing FastAPI app):
+        >>> from fastapi import FastAPI
+        >>>
+        >>> app = FastAPI()
+        >>> agent_server = AgentRunServer(invoke_agent=invoke_agent)
+        >>> app.mount("/agent", agent_server.as_fastapi_app())
+        # 可访问 / Accessible: POST http://localhost:8000/agent/v1/chat/completions
+    """
+
+    def __init__(
+        self,
+        invoke_agent: InvokeAgentHandler,
+        protocols: Optional[List[ProtocolHandler]] = None,
+        prefix_overrides: Optional[Dict[str, str]] = None,
+    ):
+        """初始化 AgentRun Server / Initialize AgentRun Server
+
+        Args:
+            invoke_agent: Agent 调用回调函数 / Agent invocation callback function
+                - 可以是同步或异步函数 / Can be synchronous or asynchronous function
+                - 支持返回字符串、AgentResponse 或生成器 / Supports returning string, AgentResponse or generator
+
+            protocols: 协议处理器列表 / List of protocol handlers
+                - 默认使用 OpenAI 协议 / Default uses OpenAI protocol
+                - 可以添加自定义协议 / Can add custom protocols
+
+            prefix_overrides: 协议前缀覆盖 / Protocol prefix overrides
+                - 格式 / Format: {协议类名 / protocol class name: 前缀 / prefix}
+                - 例如 / Example: {"OpenAIProtocolHandler": "/api/v1"}
+        """
+        self.app = FastAPI(title="AgentRun Server")
+        self.agent_invoker = AgentInvoker(invoke_agent)
+
+        # 默认使用 OpenAI 协议
+        if protocols is None:
+            protocols = [OpenAIProtocolHandler()]
+
+        self.prefix_overrides = prefix_overrides or {}
+
+        # 挂载所有协议的 Router
+        self._mount_protocols(protocols)
+
+    def _mount_protocols(self, protocols: List[ProtocolHandler]):
+        """挂载所有协议的路由
+
+        Args:
+            protocols: 协议处理器列表
+        """
+        for protocol in protocols:
+            # 获取协议的 Router
+            router = protocol.as_fastapi_router(self.agent_invoker)
+
+            # 确定路由前缀
+            prefix = self._get_protocol_prefix(protocol)
+
+            # 挂载到主应用
+            self.app.include_router(router, prefix=prefix)
+
+            logger.info(
+                f"✅ 已挂载协议: {protocol.__class__.__name__} ->"
+                f" {prefix or '(无前缀)'}"
+            )
+
+    def _get_protocol_prefix(self, protocol: ProtocolHandler) -> str:
+        """获取协议的路由前缀
+
+        优先级:
+        1. 用户指定的覆盖前缀
+        2. 协议自己的建议前缀
+        3. 基于协议类名的默认前缀
+
+        Args:
+            protocol: 协议处理器
+
+        Returns:
+            str: 路由前缀
+        """
+        protocol_name = protocol.__class__.__name__
+
+        # 1. 检查用户覆盖
+        if protocol_name in self.prefix_overrides:
+            return self.prefix_overrides[protocol_name]
+
+        # 2. 使用协议建议
+        suggested_prefix = protocol.get_prefix()
+        if suggested_prefix:
+            return suggested_prefix
+
+        # 3. 默认前缀(基于类名)
+        # OpenAIProtocolHandler -> /openai
+        name_without_handler = protocol_name.replace(
+            "ProtocolHandler", ""
+        ).replace("Handler", "")
+        return f"/{name_without_handler.lower()}"
+
+    def start(
+        self,
+        host: str = "0.0.0.0",
+        port: int = 9000,
+        log_level: str = "info",
+        **kwargs: Any,
+    ):
+        """启动 HTTP 服务器
+
+        Args:
+            host: 监听地址,默认 0.0.0.0
+            port: 监听端口,默认 9000
+            log_level: 日志级别,默认 info
+            **kwargs: 传递给 uvicorn.run 的其他参数
+        """
+        logger.info(f"🚀 启动 AgentRun Server: http://{host}:{port}")
+
+        # 打印路由信息
+        # for route in self.app.routes:
+        #     if hasattr(route, "methods") and hasattr(route, "path"):
+        #         methods = ", ".join(route.methods)  # type: ignore
+        # logger.info(f"   {methods:10} {route.path}")  # type: ignore
+
+        uvicorn.run(
+            self.app, host=host, port=port, log_level=log_level, **kwargs
+        )
+
+    def as_fastapi_app(self) -> FastAPI:
+        """导出 FastAPI 应用
+
+        用于集成到现有的 FastAPI 项目中。
+
+        Returns:
+            FastAPI: FastAPI 应用实例
+
+        Example:
+            >>> from fastapi import FastAPI
+            >>>
+            >>> app = FastAPI()
+            >>> agent_server = AgentRunServer(invoke_agent=invoke_agent)
+            >>> app.mount("/agent", agent_server.as_fastapi_app())
+        """
+        return self.app

agentrun/toolset/__client_async_template.py

@@ -0,0 +1,62 @@
+"""ToolSet 客户端 / ToolSet Client
+
+此模块提供工具集的客户端API。
+This module provides the client API for toolsets.
+"""
+
+from typing import Optional
+
+from alibabacloud_devs20230714.models import ListToolsetsRequest
+
+from agentrun.toolset.api.control import ToolControlAPI
+from agentrun.toolset.model import ToolSetListInput
+from agentrun.utils.config import Config
+from agentrun.utils.exception import HTTPError
+
+from .toolset import ToolSet
+
+
+class ToolSetClient:
+    """ToolSet 客户端 / ToolSet Client
+
+    提供工具集的获取和列表功能。
+    Provides get and list functions for toolsets.
+    """
+
+    def __init__(self, config: Optional[Config] = None):
+        """初始化客户端 / Initialize client
+
+        Args:
+            config: 配置对象,可选 / Configuration object, optional
+        """
+        self.__control_api = ToolControlAPI(config)
+
+    async def get_async(
+        self,
+        name: str,
+        config: Optional[Config] = None,
+    ):
+        try:
+            result = await self.__control_api.get_toolset_async(
+                name=name,
+                config=config,
+            )
+        except HTTPError as e:
+            raise e.to_resource_error("ToolSet", name) from e
+
+        return ToolSet.from_inner_object(result)
+
+    async def list_async(
+        self,
+        input: Optional[ToolSetListInput] = None,
+        config: Optional[Config] = None,
+    ):
+        if input is None:
+            input = ToolSetListInput()
+
+        result = await self.__control_api.list_toolsets_async(
+            input=ListToolsetsRequest().from_map(input.model_dump()),
+            config=config,
+        )
+
+        return [ToolSet.from_inner_object(item) for item in result.data]

agentrun/toolset/__init__.py

@@ -0,0 +1,51 @@
+"""ToolSet 模块 / ToolSet Module
+
+此模块提供工具集管理功能。
+This module provides toolset management functionality.
+"""
+
+from .api import ApiSet, MCPSession, MCPToolSet, OpenAPI, ToolControlAPI
+from .client import ToolSetClient
+from .model import (
+    APIKeyAuthParameter,
+    Authorization,
+    AuthorizationParameters,
+    MCPServerConfig,
+    OpenAPIToolMeta,
+    SchemaType,
+    ToolInfo,
+    ToolMeta,
+    ToolSchema,
+    ToolSetListInput,
+    ToolSetSchema,
+    ToolSetSpec,
+    ToolSetStatus,
+    ToolSetStatusOutputs,
+    ToolSetStatusOutputsUrls,
+)
+from .toolset import ToolSet
+
+__all__ = [
+    "ToolControlAPI",
+    "MCPSession",
+    "MCPToolSet",
+    "OpenAPI",
+    "ApiSet",
+    "ToolSetListInput",
+    "ToolSetClient",
+    "ToolSet",
+    "SchemaType",
+    "ToolSetStatusOutputsUrls",
+    "MCPServerConfig",
+    "ToolMeta",
+    "ToolInfo",
+    "ToolSchema",
+    "OpenAPIToolMeta",
+    "ToolSetStatusOutputs",
+    "APIKeyAuthParameter",
+    "AuthorizationParameters",
+    "Authorization",
+    "ToolSetSchema",
+    "ToolSetSpec",
+    "ToolSetStatus",
+]

agentrun/toolset/__toolset_async_template.py

@@ -0,0 +1,204 @@
+"""ToolSet 资源类 / ToolSet Resource Class
+
+提供工具集资源的面向对象封装和完整生命周期管理。
+Provides object-oriented wrapper and complete lifecycle management for toolset resources.
+"""
+
+from typing import Any, Dict, Optional, Tuple
+
+import pydash
+
+from agentrun.utils.config import Config
+from agentrun.utils.log import logger
+from agentrun.utils.model import BaseModel
+
+from .api.openapi import OpenAPI
+from .model import (
+    MCPServerConfig,
+    SchemaType,
+    ToolInfo,
+    ToolSetSpec,
+    ToolSetStatus,
+)
+
+
+class ToolSet(BaseModel):
+    """工具集资源 / ToolSet Resource
+
+    提供工具集的查询、调用等功能。
+    Provides query, invocation and other functionality for toolsets.
+
+    Attributes:
+        created_time: 创建时间 / Creation time
+        description: 描述 / Description
+        generation: 版本号 / Generation number
+        kind: 资源类型 / Resource kind
+        labels: 标签 / Labels
+        name: 工具集名称 / ToolSet name
+        spec: 规格配置 / Specification
+        status: 状态 / Status
+        uid: 唯一标识符 / Unique identifier
+    """
+
+    created_time: Optional[str] = None
+    description: Optional[str] = None
+    generation: Optional[int] = None
+    kind: Optional[str] = None
+    labels: Optional[Dict[str, str]] = None
+    name: Optional[str] = None
+    spec: Optional[ToolSetSpec] = None
+    status: Optional[ToolSetStatus] = None
+    uid: Optional[str] = None
+
+    @classmethod
+    def __get_client(cls, config: Optional[Config] = None):
+        from .client import ToolSetClient
+
+        return ToolSetClient(config)
+
+    @classmethod
+    async def get_by_name_async(
+        cls, name: str, config: Optional[Config] = None
+    ):
+        cli = cls.__get_client(config)
+        return await cli.get_async(name=name)
+
+    def type(self):
+        return SchemaType(pydash.get(self, "spec.tool_schema.type", ""))
+
+    def _get_openapi_auth_defaults(
+        self,
+    ) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+        headers: Dict[str, Any] = {}
+        query: Dict[str, Any] = {}
+
+        auth_config = pydash.get(self, "spec.auth_config", None)
+        auth_type = getattr(auth_config, "type", None) if auth_config else None
+
+        if auth_type == "APIKey":
+            api_key_param = pydash.get(
+                auth_config,
+                "parameters.api_key_parameter",
+                None,
+            )
+            if api_key_param:
+                key = getattr(api_key_param, "key", None)
+                value = getattr(api_key_param, "value", None)
+                location = getattr(api_key_param, "in_", None)
+                if key and value is not None:
+                    if location == "header":
+                        headers[key] = value
+                    elif location == "query":
+                        query[key] = value
+
+        return headers, query
+
+    def _get_openapi_base_url(self) -> Optional[str]:
+        return pydash.get(
+            self,
+            "status.outputs.urls.intranet_url",
+            None,
+        ) or pydash.get(self, "status.outputs.urls.internet_url", None)
+
+    async def get_async(self, config: Optional[Config] = None):
+        if self.name is None:
+            raise ValueError("ToolSet name is required to get the ToolSet.")
+
+        result = await self.get_by_name_async(name=self.name, config=config)
+        return self.update_self(result)
+
+    async def list_tools_async(self, config: Optional[Config] = None):
+        """异步获取工具列表,返回统一的 ToolInfo 列表"""
+        if self.type() == SchemaType.MCP:
+            mcp_tools = pydash.get(self, "status.outputs.tools", [])
+            return [ToolInfo.from_mcp_tool(tool) for tool in mcp_tools]
+        elif self.type() == SchemaType.OpenAPI:
+            # 直接使用 to_apiset 转换
+            apiset = self.to_apiset(config=config)
+            return apiset.tools()
+        return []
+
+    async def call_tool_async(
+        self,
+        name: str,
+        arguments: Optional[Dict[str, str]] = None,
+        config: Optional[Config] = None,
+    ):
+        """异步调用工具,统一使用 ApiSet 实现"""
+        apiset = self.to_apiset(config=config)
+
+        # 对于 OpenAPI,可能需要解析 operation name
+        if self.type() == SchemaType.OpenAPI:
+            # 尝试查找实际的 operation name
+            tool = apiset.get_tool(name)
+            if tool is None:
+                # 尝试通过 tool_id 映射查找
+                openapi_tools = (
+                    pydash.get(self, "status.outputs.open_api_tools", []) or []
+                )
+                for tool_meta in openapi_tools:
+                    if tool_meta is None:
+                        continue
+                    if hasattr(tool_meta, "model_dump"):
+                        tool_meta = tool_meta.model_dump()
+                    if not isinstance(tool_meta, dict):
+                        continue
+                    if tool_meta.get("tool_id") == name:
+                        name = tool_meta.get("tool_name") or name
+                        break
+
+        logger.debug("invoke tool %s with arguments %s", name, arguments)
+        result = await apiset.invoke_async(
+            name=name, arguments=arguments, config=config
+        )
+        logger.debug("invoke tool %s got result %s", name, result)
+        return result
+
+    def to_apiset(self, config: Optional[Config] = None):
+        """将 ToolSet 转换为统一的 ApiSet 对象
+
+        Returns:
+            ApiSet: 统一的工具集接口
+        """
+        from .api.openapi import ApiSet
+
+        if self.type() == SchemaType.MCP:
+            from .api.mcp import MCPToolSet
+
+            mcp_server_config: MCPServerConfig = pydash.get(
+                self, "status.outputs.mcp_server_config", None
+            )
+            assert (
+                mcp_server_config.url is not None
+            ), "MCP server URL is missing."
+
+            cfg = Config.with_configs(
+                config, Config(headers=mcp_server_config.headers)
+            )
+
+            mcp_client = MCPToolSet(
+                url=mcp_server_config.url,
+                config=cfg,
+            )
+
+            # 获取 MCP tools
+            mcp_tools = pydash.get(self, "status.outputs.tools", [])
+
+            return ApiSet.from_mcp_tools(
+                tools=mcp_tools,
+                mcp_client=mcp_client,
+                config=cfg,
+            )
+
+        elif self.type() == SchemaType.OpenAPI:
+            headers, query = self._get_openapi_auth_defaults()
+
+            return ApiSet.from_openapi_schema(
+                schema=pydash.get(self, "spec.tool_schema.detail", None),
+                base_url=self._get_openapi_base_url(),
+                headers=headers,
+                query_params=query,
+                config=config,
+            )
+
+        raise ValueError(f"Unsupported ToolSet type: {self.type()}")

agentrun/toolset/api/__init__.py

@@ -0,0 +1,17 @@
+"""ToolSet API 模块 / ToolSet API Module
+
+此模块包含工具集的 API 接口。
+This module contains API interfaces for toolsets.
+"""
+
+from .control import ToolControlAPI
+from .mcp import MCPSession, MCPToolSet
+from .openapi import ApiSet, OpenAPI
+
+__all__ = [
+    "ToolControlAPI",
+    "MCPSession",
+    "MCPToolSet",
+    "OpenAPI",
+    "ApiSet",
+]