feat(agent_runtime): align SDK model with official agentrun-20250910

.github/workflows/ci.yml

@@ -163,6 +163,10 @@ jobs:
       with:
         password: ${{ secrets.PYPI_API_TOKEN }}
         verify-metadata: false
+        # 当 PR 多次 push 或并发 CI 跑出相同版本号时，跳过已存在版本而非报错。
+        # 根因是版本号自增逻辑依赖 PyPI API 拉取最新版本，存在缓存/并发窗口。
+        # 不阻塞 PR 合入即可，长期方案是在版本号中嵌入 commit SHA 实现唯一化。
+        skip-existing: true
 
     - name: Create and push tag
       if: steps.changes.outputs.agentrun_changed == 'true'

.github/workflows/e2e.yml

@@ -0,0 +1,86 @@
+name: E2E Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+# OIDC token generation requires id-token:write permission
+permissions:
+  id-token: write
+  contents: read
+
+# Prevent parallel e2e runs from conflicting on shared test resources
+concurrency:
+  group: e2e-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    # Skip e2e for PRs from forks (they cannot access OIDC secrets)
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      github.event_name == 'push' ||
+      (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository)
+    strategy:
+      matrix:
+        python-version: ['3.10']
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        make setup PYTHON_VERSION=${{ matrix.python-version }}
+
+    # Obtain temporary Alibaba Cloud credentials via OIDC (keyless)
+    # This action exchanges the GitHub OIDC token for temporary AK/SK/SecurityToken
+    # and exports them as ALIBABA_CLOUD_ACCESS_KEY_ID, ALIBABA_CLOUD_ACCESS_KEY_SECRET,
+    # ALIBABA_CLOUD_SECURITY_TOKEN environment variables.
+    - name: Configure Alibaba Cloud credentials (OIDC)
+      uses: aliyun/configure-aliyun-credentials-action@v1
+      with:
+        role-to-assume: ${{ secrets.ALIBABA_CLOUD_OIDC_ROLE_ARN }}
+        oidc-provider-arn: ${{ secrets.ALIBABA_CLOUD_OIDC_PROVIDER_ARN }}
+        role-session-name: agentrun-e2e-${{ github.run_id }}
+        role-session-expiration: 3600
+
+    - name: Run E2E tests
+      env:
+        # Credentials are auto-injected by configure-aliyun-credentials-action:
+        #   ALIBABA_CLOUD_ACCESS_KEY_ID
+        #   ALIBABA_CLOUD_ACCESS_KEY_SECRET
+        #   ALIBABA_CLOUD_SECURITY_TOKEN
+        AGENTRUN_ACCOUNT_ID: ${{ secrets.AGENTRUN_ACCOUNT_ID }}
+        AGENTRUN_REGION: ${{ secrets.AGENTRUN_REGION }}
+        AGENTRUN_CONTROL_ENDPOINT: ${{ secrets.AGENTRUN_CONTROL_ENDPOINT }}
+        AGENTRUN_DATA_ENDPOINT: ${{ secrets.AGENTRUN_DATA_ENDPOINT }}
+        # API_KEY and AGENTRUN_TEST_WORKSPACE_ID are intentionally NOT set.
+        # Tests requiring them are excluded via --ignore and -k filters below.
+      run: |
+        uv run pytest tests/e2e/ -v --tb=short \
+          --ignore=tests/e2e/integration \
+          --ignore=tests/e2e/test_agent_ruintime.py \
+          --ignore=tests/e2e/test_workspace_id.py \
+          --ignore=tests/e2e/test_sandbox_browser.py \
+          --ignore=tests/e2e/test_sandbox_code_interpreter.py \
+          -k "not (invoke or with_credential or model_proxy or process_get or delete_sandbox or delete_nonexistent_sandbox or connect_nonexistent or connect_sandbox_async or sandbox_lifecycle or connect_with_wrong_template or template_validation_code_interpreter_network)"
+
+    - name: E2E Summary
+      if: always()
+      run: |
+        echo "## E2E Test Results" >> $GITHUB_STEP_SUMMARY
+        echo "" >> $GITHUB_STEP_SUMMARY
+        echo "- **Trigger:** ${{ github.event_name }}" >> $GITHUB_STEP_SUMMARY
+        echo "- **Branch:** ${{ github.ref_name }}" >> $GITHUB_STEP_SUMMARY
+        echo "- **Commit:** ${{ github.sha }}" >> $GITHUB_STEP_SUMMARY
+        echo "- **Auth:** OIDC keyless (temporary credentials)" >> $GITHUB_STEP_SUMMARY

RELEASE_NOTES.md

@@ -0,0 +1,57 @@
+# Release Notes
+
+## Unreleased
+
+### Breaking Changes
+
+- Sandbox data-plane HTTP JSON APIs now follow standard HTTP error handling:
+  - `2xx` responses return the business response body.
+  - `4xx` responses raise `ClientError`.
+  - `5xx` responses raise `ServerError`.
+- Error responses such as `{"code": "...", "requestId": "...", "message": "..."}`
+  are no longer returned as normal dictionaries for Sandbox HTTP JSON APIs. The
+  fields are exposed on the raised exception as `error_code`, `request_id`, and
+  `message`.
+- Existing code that checked returned dictionaries for `code` and `requestId`
+  must migrate to `try` / `except ClientError` / `except ServerError`.
+- `HTTPError.__str__()` output format has changed. The old format unconditionally
+  included `"Request ID: None. Details: {}"` even when those fields were empty.
+  The new format only includes non-empty fields and uses `". "` as separator.
+  Code that parses this string representation (e.g. log parsers or test assertions
+  on `str(error)`) must be updated.
+
+### Migration
+
+Before:
+
+```python
+resp = ci.cmd(command="echo hello", cwd="/tmp", timeout=30)
+if "code" in resp and "requestId" in resp:
+    raise RuntimeError(resp["message"])
+```
+
+After:
+
+```python
+from agentrun.utils.exception import ClientError, ServerError
+
+try:
+    resp = ci.cmd(command="echo hello", cwd="/tmp", timeout=30)
+except ClientError as e:
+    print(e.status_code, e.error_code, e.request_id, e.message)
+    raise
+except ServerError as e:
+    print(e.status_code, e.error_code, e.request_id, e.message)
+    raise
+```
+
+Command execution failures are still business-level failures and should be
+handled by checking `resp["result"]["exitCode"]` after a successful HTTP
+response.
+
+### Scope
+
+This change is intentionally limited to Sandbox data-plane HTTP JSON APIs. It
+does not change WebSocket/CDP/VNC URL generation, Playwright connections, file
+upload/download helpers, video download helpers, or non-Sandbox data-plane
+clients.

agentrun/__init__.py

@@ -19,7 +19,7 @@
 import os
 from typing import TYPE_CHECKING
 
-__version__ = "0.0.34"
+__version__ = "0.0.35"
 
 
 # Agent Runtime

agentrun/agent_runtime/__client_async_template.py

@@ -18,6 +18,12 @@
 )
 from typing_extensions import Unpack
 
+from agentrun.agent_runtime._workspace import (
+    resolve_workspace_id_by_name,
+    resolve_workspace_id_by_name_async,
+    resolve_workspace_ids_by_names,
+    resolve_workspace_ids_by_names_async,
+)
 from agentrun.agent_runtime.api.data import InvokeArgs
 from agentrun.agent_runtime.model import (
     AgentRuntimeArtifact,
@@ -68,11 +74,26 @@ async def create_async(
             AgentRuntime: 创建的 Agent Runtime 对象 / Created Agent Runtime object
 
         Raises:
-            ValueError: 当既未提供代码配置也未提供容器配置时 / When neither code nor container configuration is provided
+            ValueError: 当既未提供代码配置也未提供容器配置时；或同时传入
+                workspace_id 与 workspace_name / When neither code nor container
+                configuration is provided, or when workspace_id and workspace_name
+                are both set
             ResourceAlreadyExistError: 资源已存在 / Resource already exists
-            ResourceNotExistError: 资源不存在 / Resource does not exist
+            ResourceNotExistError: 资源不存在；或 workspace_name 在该账号下未找到
+                / Resource does not exist, or no workspace matches workspace_name
             HTTPError: HTTP 请求错误 / HTTP request error
         """
+        if input.workspace_id and input.workspace_name:
+            raise ValueError(
+                "workspace_id and workspace_name are mutually exclusive; please"
+                " only set one of them."
+            )
+        if input.workspace_name:
+            input.workspace_id = await resolve_workspace_id_by_name_async(
+                input.workspace_name, config
+            )
+            input.workspace_name = None
+
         if input.network_configuration is None:
             input.network_configuration = NetworkConfig()
 
@@ -198,12 +219,41 @@ async def list_async(
             List[AgentRuntime]: Agent Runtime 对象列表 / List of Agent Runtime objects
 
         Raises:
+            ValueError: 同时传入 workspace_id 与 workspace_name，或同时传入
+                workspace_ids 与 workspace_names / When workspace_id and
+                workspace_name (or workspace_ids and workspace_names) are
+                both set
+            ResourceNotExistError: workspace_name(s) 在该账号下未找到
+                / No workspace matches the given workspace_name(s)
             HTTPError: HTTP 请求错误 / HTTP request error
         """
         try:
             if input is None:
                 input = AgentRuntimeListInput()
 
+            if input.workspace_id and input.workspace_name:
+                raise ValueError(
+                    "workspace_id and workspace_name are mutually exclusive;"
+                    " please only set one of them."
+                )
+            if input.workspace_ids and input.workspace_names:
+                raise ValueError(
+                    "workspace_ids and workspace_names are mutually exclusive;"
+                    " please only set one of them."
+                )
+            if input.workspace_name:
+                input.workspace_id = await resolve_workspace_id_by_name_async(
+                    input.workspace_name, config
+                )
+                input.workspace_name = None
+            if input.workspace_names:
+                input.workspace_ids = (
+                    await resolve_workspace_ids_by_names_async(
+                        input.workspace_names, config
+                    )
+                )
+                input.workspace_names = None
+
             results = await self.__control_api.list_agent_runtimes_async(
                 ListAgentRuntimesRequest().from_map(input.model_dump()),
                 config=config,

agentrun/agent_runtime/__endpoint_async_template.py

@@ -67,7 +67,7 @@ async def create_by_id_async(
             ResourceNotExistError: Agent Runtime 不存在 / Agent Runtime does not exist
             HTTPError: HTTP 请求错误 / HTTP request error
         """
-        cli = cls.__get_client()
+        cli = cls.__get_client(config=config)
         return await cli.create_endpoint_async(
             agent_runtime_id,
             input,
@@ -95,7 +95,7 @@ async def delete_by_id_async(
             ResourceNotExistError: 资源不存在 / Resource does not exist
             HTTPError: HTTP 请求错误 / HTTP request error
         """
-        cli = cls.__get_client()
+        cli = cls.__get_client(config=config)
         return await cli.delete_endpoint_async(
             agent_runtime_id,
             endpoint_id,
@@ -125,7 +125,7 @@ async def update_by_id_async(
             ResourceNotExistError: 资源不存在 / Resource does not exist
             HTTPError: HTTP 请求错误 / HTTP request error
         """
-        cli = cls.__get_client()
+        cli = cls.__get_client(config=config)
         return await cli.update_endpoint_async(
             agent_runtime_id,
             endpoint_id,
@@ -154,7 +154,7 @@ async def get_by_id_async(
             ResourceNotExistError: 资源不存在 / Resource does not exist
             HTTPError: HTTP 请求错误 / HTTP request error
         """
-        cli = cls.__get_client()
+        cli = cls.__get_client(config=config)
         return await cli.get_endpoint_async(
             agent_runtime_id,
             endpoint_id,
@@ -191,7 +191,7 @@ async def _list_page_async(
                 "agent_runtime_id is required for listing endpoints"
             )
 
-        return await cls.__get_client().list_endpoints_async(
+        return await cls.__get_client(config=config).list_endpoints_async(
             agent_runtime_id,
             AgentRuntimeEndpointListInput(
                 page_number=page_input.page_number,
@@ -219,7 +219,7 @@ async def list_by_id_async(
         Raises:
             HTTPError: HTTP 请求错误 / HTTP request error
         """
-        cli = cls.__get_client()
+        cli = cls.__get_client(config=config)
 
         endpoints: List[AgentRuntimeEndpoint] = []
         page = 1
@@ -339,7 +339,9 @@ async def get_async(self, config: Optional[Config] = None):
             )
 
         result = await self.get_by_id_async(
-            self.agent_runtime_id, self.agent_runtime_endpoint_id
+            self.agent_runtime_id,
+            self.agent_runtime_endpoint_id,
+            config=config,
         )
         self.update_self(result)
         return self