agentcore-sdk-agentrun-compat-core 0.1.0__py3-none-any.whl

agentcore/__init__.py

@@ -0,0 +1,381 @@
+"""AgentCore Python SDK
+
+对标 AgentRun SDK (`agentrun-sdk`) 的 Python 客户端库，基于 AgentCore
+CloudSpec（2026-08-04，14 资源 148 API）构建。
+
+Drop-in Replacement 用法:
+    # 改前
+    from agentrun.agent_runtime import AgentRuntimeClient
+    from agentrun.agent_runtime.model import AgentRuntimeCreateInput, AgentRuntimeCode, AgentRuntimeLanguage
+
+    # 改后（仅替换 package 名）
+    from agentcore.agent_runtime import AgentRuntimeClient
+    from agentcore.agent_runtime.model import AgentRuntimeCreateInput, AgentRuntimeCode, AgentRuntimeLanguage
+
+主要功能：
+- agent_runtime: Agent Runtime 管理（对标 AgentRun 的 agent_runtime）
+- credential: 凭证管理
+- model: 模型服务管理（ModelService → ModelConnection + Model）
+- mcp: MCP Server 管理（对标 AgentRun 的 MCP 能力）
+- skill: 技能管理（Draft/发布）
+- tool / toolset: 工具发现与工具集声明（工具来自 MCP）
+- sandbox: 沙箱（兼容层，AgentCore 无公开沙箱 API，操作抛 NotImplementedError + 缺口编号）
+- server: AgentRun 兼容的本地 OpenAI / AG-UI HTTP 服务
+- integration: 框架集成（桩模块）
+
+安装:
+    pip install agentcore-sdk-agentrun-compat
+
+环境变量（按最小透出定义：有行业标准的用标准，没标准且必需的才自己定）:
+    AGENTCORE_WORKSPACE_ID          — 工作空间 ID（拼进请求路径）
+    AGENTCORE_ENDPOINT              — 服务端点（默认按 region 拼 https://agentcore.{region}.aliyuncs.com）
+    AGENTCORE_REGION_ID             — 控制面 region（默认从 FC_REGION / ALIBABA_CLOUD_REGION_ID 解析，回落 cn-hangzhou）
+    AGENTCORE_API_VERSION           — OpenAPI 版本
+    AGENTCORE_SDK_DEBUG=1           — 开启调试日志
+    ALIBABA_CLOUD_ACCESS_KEY_ID     — Access Key ID（阿里云标准）
+    ALIBABA_CLOUD_ACCESS_KEY_SECRET — Access Key Secret（阿里云标准）
+    ALIBABA_CLOUD_SECURITY_TOKEN    — STS Token（阿里云标准）
+
+迁移期兼容：凭证与调试开关同时接受 AGENTRUN_* 旧名（会抛 DeprecationWarning）。
+目标形态下此行为由独立迁移包提供，与主线包生命周期解耦，
+详见 docs/COMPATIBILITY.md 第 3 节。
+"""
+
+from typing import TYPE_CHECKING
+
+__version__ = "0.1.0"
+
+# Config
+from agentcore.utils.config import Config
+
+# Agent Runtime
+from agentcore.agent_runtime import (
+    AgentRuntimeClient,
+    AgentRuntime,
+    AgentRuntimeEndpoint,
+    AgentRuntimeArtifact,
+    AgentRuntimeCode,
+    AgentRuntimeContainer,
+    AgentRuntimeCreateInput,
+    AgentRuntimeUpdateInput,
+    AgentRuntimeListInput,
+    AgentRuntimeLanguage,
+    AgentRuntimeProtocolType,
+    AgentRuntimeHealthCheckConfig,
+    AgentRuntimeLogConfig,
+    AgentRuntimeProtocolConfig,
+    AgentRuntimeEndpointCreateInput,
+    AgentRuntimeEndpointUpdateInput,
+    AgentRuntimeEndpointListInput,
+    AgentRuntimeEndpointRoutingConfig,
+    AgentRuntimeEndpointRoutingWeight,
+    Status,
+)
+
+# Credential
+from agentcore.credential import (
+    CredentialClient,
+    Credential,
+    CredentialBasicAuth,
+    CredentialConfig,
+    CredentialCreateInput,
+    CredentialUpdateInput,
+    CredentialListInput,
+    RelatedResource,
+)
+
+# Model
+from agentcore.model import (
+    ModelClient,
+    ModelService,
+    ModelProxy,
+    BackendType,
+    ModelType,
+    Provider,
+    ProviderSettings,
+    ModelFeatures,
+    ModelProperties,
+    ModelParameterRule,
+    ModelInfoConfig,
+    ProxyConfig,
+    ProxyConfigEndpoint,
+    ProxyConfigFallback,
+    ProxyConfigPolicies,
+    ModelServiceCreateInput,
+    ModelServiceUpdateInput,
+    ModelServiceListInput,
+    ModelProxyCreateInput,
+    ModelProxyUpdateInput,
+    ModelProxyListInput,
+)
+
+# Exceptions
+from agentcore.utils.exception import (
+    AgentCoreError,
+    HTTPError,
+    ResourceAlreadyExistError,
+    ResourceNotExistError,
+    ValidationError,
+    ConfigError,
+    CompatibilityWarning,
+)
+
+# MCP
+from agentcore.mcp import (
+    McpClient,
+    McpServer,
+    McpTool,
+    McpCreateInput,
+    McpUpdateInput,
+    McpAddress,
+    McpType,
+    McpProtocol,
+)
+
+# Skill
+from agentcore.skill import SkillClient, Skill, SkillCreateInput, SkillUpdateInput
+
+# Tool / Toolset
+from agentcore.tool import ToolClient, Tool
+from agentcore.toolset import ToolsetClient, Toolset, ToolsetCreateInput
+
+# SuperAgent（组合实现：ManagedAgent.subAgents[]）
+from agentcore.super_agent import (
+    SuperAgent,
+    SuperAgentClient,
+    SuperAgentCreateInput,
+    SuperAgentUpdateInput,
+    SuperAgentListInput,
+)
+
+# Sandbox（兼容层，操作抛 NotImplementedError + OpenAPI 缺口编号 GAP-4）
+from agentcore.sandbox import (
+    SandboxClient,
+    Sandbox,
+    Template,
+    CodeInterpreterSandbox,
+    BrowserSandbox,
+    AioSandbox,
+    CustomSandbox,
+    SandboxInput,
+    TemplateInput,
+    TemplateType,
+    TemplateNetworkMode,
+    CodeLanguage,
+)
+
+# Server 在根包做延迟导出，避免基础包 import 时强制加载
+# fastapi / uvicorn / ag-ui-protocol；安装 [server] 后对象仍来自同一实现模块。
+if TYPE_CHECKING:
+    from agentcore.server import (
+        AGUIProtocolConfig,
+        AGUIProtocolHandler,
+        AgentEvent,
+        AgentEventItem,
+        AgentRequest,
+        AgentResult,
+        AgentResultItem,
+        AgentReturnType,
+        AgentRunServer,
+        AguiEventNormalizer,
+        AsyncAgentEventGenerator,
+        AsyncAgentResultGenerator,
+        AsyncInvokeAgentHandler,
+        BaseProtocolHandler,
+        EventType,
+        InvokeAgentHandler,
+        Message,
+        MessageRole,
+        OpenAIProtocolConfig,
+        OpenAIProtocolHandler,
+        ProtocolConfig,
+        ProtocolHandler,
+        ServerConfig,
+        SyncAgentEventGenerator,
+        SyncAgentResultGenerator,
+        SyncInvokeAgentHandler,
+        ToolCall,
+    )
+
+# ── 官方根包导出面的补齐 ──────────────────────────────────────
+# 官方 `agentrun/__init__.py` 的 `__all__` 有 123 个符号，客户最常写的就是
+# `from agentrun import X`。此前本包根命名空间缺 59 个——这是最致命的一面，
+# 却也是符号闸门的盲区（闸门只扫子包 `__init__.py`，不扫根包），现已纳入快照。
+#
+# 官方部分名字做了重命名导出（`super_agent.Message` → `SuperAgentMessage`、
+# `tool.Tool` → `ToolResource`），照抄别名，不改。
+from agentcore.agent_runtime import AgentRuntimeControlAPI
+from agentcore.credential import CredentialControlAPI
+from agentcore.model import ModelCompletionAPI, ModelControlAPI, ModelDataAPI
+from agentcore.super_agent import (
+    ConversationInfo,
+    InvokeResponseData,
+    InvokeStream,
+    SSEEvent,
+)
+from agentcore.super_agent import Message as SuperAgentMessage
+from agentcore.tool import Tool as ToolResource
+from agentcore.tool import ToolClient as ToolResourceClient
+from agentcore.tool import ToolControlAPI as ToolResourceControlAPI
+from agentcore.toolset import ToolSet, ToolSetClient
+from agentcore.utils.credential_context import (
+    StsCredential,
+    use_sts_credentials,
+    use_sts_from_headers,
+)
+
+# `MergeOptions` 官方是从 `agentrun.server` 转出来的；本 SDK 取 `utils.helper` 的实现
+# （同名同语义、且是纯本地类型），不让它跟着 server 桩一起报错。
+from agentcore.utils.helper import MergeOptions
+
+# ── 桩包符号：惰性解析 ────────────────────────────────────────
+# 不能在这里 eager import：桩包用模块级 `__getattr__` 抛 NotImplementedError，
+# 顶层导入会让 `import agentcore` 直接崩。改成访问时才解析——`import` 成功、
+# 取用时抛带指引的错误，与桩包本身的约定一致。
+_STUB_EXPORTS = {
+    # agentcore.memory_collection（GAP-3）
+    "EmbedderConfig": "agentcore.memory_collection",
+    "EmbedderConfigConfig": "agentcore.memory_collection",
+    "LLMConfig": "agentcore.memory_collection",
+    "LLMConfigConfig": "agentcore.memory_collection",
+    "MemoryCollection": "agentcore.memory_collection",
+    "MemoryCollectionClient": "agentcore.memory_collection",
+    "MemoryCollectionCreateInput": "agentcore.memory_collection",
+    "MemoryCollectionListInput": "agentcore.memory_collection",
+    "MemoryCollectionListOutput": "agentcore.memory_collection",
+    "MemoryCollectionUpdateInput": "agentcore.memory_collection",
+    "NetworkConfiguration": "agentcore.memory_collection",
+    "VectorStoreConfig": "agentcore.memory_collection",
+    "VectorStoreConfigConfig": "agentcore.memory_collection",
+}
+
+_SERVER_EXPORTS = {
+    "AgentRunServer",
+    "ServerConfig",
+    "ProtocolConfig",
+    "OpenAIProtocolConfig",
+    "AGUIProtocolConfig",
+    "AgentRequest",
+    "AgentEvent",
+    "AgentResult",
+    "Message",
+    "MessageRole",
+    "ToolCall",
+    "EventType",
+    "AgentEventItem",
+    "AgentResultItem",
+    "AgentReturnType",
+    "SyncAgentEventGenerator",
+    "SyncAgentResultGenerator",
+    "AsyncAgentEventGenerator",
+    "AsyncAgentResultGenerator",
+    "InvokeAgentHandler",
+    "AsyncInvokeAgentHandler",
+    "SyncInvokeAgentHandler",
+    "ProtocolHandler",
+    "BaseProtocolHandler",
+    "OpenAIProtocolHandler",
+    "AGUIProtocolHandler",
+    "AguiEventNormalizer",
+}
+
+_OPTIONAL_PACKAGES = {
+    "agentcore-sdk-agentrun-compat[server]": (
+        "fastapi",
+        "uvicorn",
+        "ag_ui",
+        "starlette",
+    ),
+}
+
+
+def __getattr__(name: str):
+    """根包的惰性符号解析：桩包符号访问即抛带指引的 NotImplementedError。"""
+    if name in _SERVER_EXPORTS:
+        try:
+            from agentcore import server
+
+            return getattr(server, name)
+        except ImportError as exc:
+            error_text = str(exc)
+            for install_command, package_names in _OPTIONAL_PACKAGES.items():
+                if any(package_name in error_text for package_name in package_names):
+                    raise ImportError(
+                        f"'{name}' requires the 'server' optional dependencies. "
+                        f"Install with: pip install {install_command}\n"
+                        f"Original error: {exc}"
+                    ) from exc
+            raise
+
+    target = _STUB_EXPORTS.get(name)
+    if target is None:
+        raise AttributeError(f"module 'agentcore' has no attribute {name!r}")
+    import importlib
+
+    return getattr(importlib.import_module(target), name)
+
+
+def __dir__() -> list[str]:
+    """让 `dir(agentcore)` / 补全能看到桩符号——否则它们像不存在。"""
+    return sorted(set(globals()) | set(_STUB_EXPORTS) | _SERVER_EXPORTS)
+
+
+__all__ = [
+    "__version__",
+    "Config",
+    # Agent Runtime
+    "AgentRuntimeClient", "AgentRuntime", "AgentRuntimeEndpoint",
+    "AgentRuntimeArtifact", "AgentRuntimeCode", "AgentRuntimeContainer",
+    "AgentRuntimeCreateInput", "AgentRuntimeUpdateInput", "AgentRuntimeListInput",
+    "AgentRuntimeLanguage", "AgentRuntimeProtocolType",
+    "AgentRuntimeHealthCheckConfig", "AgentRuntimeLogConfig", "AgentRuntimeProtocolConfig",
+    "AgentRuntimeEndpointCreateInput", "AgentRuntimeEndpointUpdateInput", "AgentRuntimeEndpointListInput",
+    "AgentRuntimeEndpointRoutingConfig", "AgentRuntimeEndpointRoutingWeight",
+    "Status",
+    # Credential
+    "CredentialClient", "Credential", "CredentialBasicAuth", "CredentialConfig",
+    "CredentialCreateInput", "CredentialUpdateInput", "CredentialListInput", "RelatedResource",
+    # Model
+    "ModelClient", "ModelService", "ModelProxy",
+    "BackendType", "ModelType", "Provider",
+    "ProviderSettings", "ModelFeatures", "ModelProperties", "ModelParameterRule", "ModelInfoConfig",
+    "ProxyConfig", "ProxyConfigEndpoint", "ProxyConfigFallback", "ProxyConfigPolicies",
+    "ModelServiceCreateInput", "ModelServiceUpdateInput", "ModelServiceListInput",
+    "ModelProxyCreateInput", "ModelProxyUpdateInput", "ModelProxyListInput",
+    # Exceptions
+    "AgentCoreError", "HTTPError", "ResourceAlreadyExistError",
+    "ResourceNotExistError", "ValidationError", "ConfigError", "CompatibilityWarning",
+    # MCP
+    "McpClient", "McpServer", "McpTool", "McpCreateInput", "McpUpdateInput",
+    "McpAddress", "McpType", "McpProtocol",
+    # Skill
+    "SkillClient", "Skill", "SkillCreateInput", "SkillUpdateInput",
+    # Tool / Toolset
+    "ToolClient", "Tool", "ToolsetClient", "Toolset", "ToolsetCreateInput",
+    # SuperAgent
+    "SuperAgent", "SuperAgentClient",
+    "SuperAgentCreateInput", "SuperAgentUpdateInput", "SuperAgentListInput",
+    # Sandbox
+    "SandboxClient", "Sandbox", "Template",
+    "CodeInterpreterSandbox", "BrowserSandbox", "AioSandbox", "CustomSandbox",
+    "SandboxInput", "TemplateInput", "TemplateType", "TemplateNetworkMode", "CodeLanguage",
+    # 官方根包导出面（重命名别名照抄官方）
+    "AgentRuntimeControlAPI", "CredentialControlAPI",
+    "ModelCompletionAPI", "ModelControlAPI", "ModelDataAPI",
+    "ConversationInfo", "InvokeResponseData", "InvokeStream", "SSEEvent", "SuperAgentMessage",
+    "ToolResource", "ToolResourceClient", "ToolResourceControlAPI",
+    "ToolSet", "ToolSetClient",
+    "MergeOptions", "StsCredential", "use_sts_credentials", "use_sts_from_headers",
+    # Server
+    "AgentRunServer", "ServerConfig", "ProtocolConfig",
+    "OpenAIProtocolConfig", "AGUIProtocolConfig", "AgentRequest", "AgentEvent",
+    "AgentResult", "Message", "MessageRole", "ToolCall", "EventType",
+    "AgentEventItem", "AgentResultItem", "AgentReturnType",
+    "SyncAgentEventGenerator", "SyncAgentResultGenerator",
+    "AsyncAgentEventGenerator", "AsyncAgentResultGenerator",
+    "InvokeAgentHandler", "AsyncInvokeAgentHandler", "SyncInvokeAgentHandler",
+    "ProtocolHandler", "BaseProtocolHandler", "OpenAIProtocolHandler",
+    "AGUIProtocolHandler", "AguiEventNormalizer",
+    # 桩包符号（惰性解析，取用即抛带指引的错误）
+    *sorted(_STUB_EXPORTS),
+]

agentcore/agent_runtime/__init__.py

@@ -0,0 +1,65 @@
+"""Agent Runtime 模块 / Agent Runtime Module
+
+对标 AgentRun SDK 的 `agentrun.agent_runtime`。
+
+`AgentRuntimeControlAPI` 是 AgentRun 的内部控制面 API 层，本 SDK 统一走
+`agentcore.api.AgentCoreAPI`；名字以桩保留（import 不报错、构造即报错并给指引）。
+"""
+
+from agentcore.utils.control_api import LEGACY_API_GUIDANCE
+from agentcore.utils.stub import make_stub_class
+
+from .client import AgentRuntimeClient
+from .endpoint import AgentRuntimeEndpoint
+from .model import (
+    AgentRuntimeArtifact,
+    AgentRuntimeCode,
+    AgentRuntimeContainer,
+    AgentRuntimeCreateInput,
+    AgentRuntimeEndpointCreateInput,
+    AgentRuntimeEndpointListInput,
+    AgentRuntimeEndpointRoutingConfig,
+    AgentRuntimeEndpointRoutingWeight,
+    AgentRuntimeEndpointUpdateInput,
+    AgentRuntimeHealthCheckConfig,
+    AgentRuntimeLanguage,
+    AgentRuntimeListInput,
+    AgentRuntimeLogConfig,
+    AgentRuntimeProtocolConfig,
+    AgentRuntimeProtocolType,
+    AgentRuntimeUpdateInput,
+    Status,
+)
+from .runtime import AgentRuntime
+
+AgentRuntimeControlAPI = make_stub_class(
+    "agentcore.agent_runtime.AgentRuntimeControlAPI", LEGACY_API_GUIDANCE
+)
+
+__all__ = [
+    "AgentRuntimeControlAPI",
+    # base
+    "AgentRuntime",
+    "AgentRuntimeEndpoint",
+    "AgentRuntimeClient",
+    # enum
+    "AgentRuntimeArtifact",
+    "AgentRuntimeLanguage",
+    "AgentRuntimeProtocolType",
+    "Status",
+    # inner model
+    "AgentRuntimeCode",
+    "AgentRuntimeContainer",
+    "AgentRuntimeHealthCheckConfig",
+    "AgentRuntimeLogConfig",
+    "AgentRuntimeProtocolConfig",
+    "AgentRuntimeEndpointRoutingConfig",
+    "AgentRuntimeEndpointRoutingWeight",
+    # api model
+    "AgentRuntimeCreateInput",
+    "AgentRuntimeUpdateInput",
+    "AgentRuntimeListInput",
+    "AgentRuntimeEndpointCreateInput",
+    "AgentRuntimeEndpointUpdateInput",
+    "AgentRuntimeEndpointListInput",
+]

agentcore/agent_runtime/api/__init__.py

@@ -0,0 +1,13 @@
+"""Agent Runtime API compatibility surface."""
+
+from agentcore.agent_runtime import AgentRuntimeControlAPI
+from agentcore.utils.openapi_gap import gap_guidance
+from agentcore.utils.stub import make_stub_class
+
+_GUIDANCE = gap_guidance("GAP-5", "AgentCore 尚未公开 Agent 调用数据面。")
+AgentRuntimeDataAPI = make_stub_class(
+    "agentcore.agent_runtime.api.AgentRuntimeDataAPI", _GUIDANCE
+)
+InvokeArgs = make_stub_class("agentcore.agent_runtime.api.InvokeArgs", _GUIDANCE)
+
+__all__ = ["AgentRuntimeControlAPI", "AgentRuntimeDataAPI", "InvokeArgs"]