feat: add support for shared internet access in runtime network configuration

Author: innsd

agentkit/toolkit/cli/cli_config.py

@@ -201,6 +201,15 @@ def config_command(
         "--runtime-subnet-ids",
         help="Runtime subnet ID (repeatable; cloud/hybrid, CreateRuntime only)",
     ),
+    runtime_enable_shared_internet_access: Optional[bool] = typer.Option(
+        None,
+        "--runtime_enable_shared_internet_access/--no-runtime_enable_shared_internet_access",
+        "--runtime-enable-shared-internet-access/--no-runtime-enable-shared-internet-access",
+        help=(
+            "Enable shared internet egress for Runtime private network "
+            "(cloud/hybrid, CreateRuntime only; effective for private/both)"
+        ),
+    ),
 ):
     """Configure AgentKit (supports interactive and non-interactive modes).
     
@@ -307,6 +316,7 @@ def config_command(
             runtime_network_mode=runtime_network_mode,
             runtime_vpc_id=runtime_vpc_id,
             runtime_subnet_ids=runtime_subnet_ids,
+            runtime_enable_shared_internet_access=runtime_enable_shared_internet_access,
         )
 
         has_cli_params = ConfigParamHandler.has_cli_params(cli_params)

agentkit/toolkit/cli/cli_runtime.py

@@ -36,6 +36,62 @@
 )
 
 
+def _build_network_for_create_runtime(
+    vpc_id: Optional[str],
+    subnet_ids: Optional[str],
+    enable_private_network: bool,
+    enable_public_network: bool,
+    enable_shared_internet_access: bool,
+) -> Optional[rt.NetworkForCreateRuntime]:
+    has_vpc_id = bool((vpc_id or "").strip())
+    has_subnet_ids = bool((subnet_ids or "").strip())
+
+    wants_private_network = (
+        enable_private_network
+        or has_vpc_id
+        or has_subnet_ids
+        or enable_shared_internet_access
+    )
+
+    if enable_shared_internet_access and not wants_private_network:
+        raise ValueError(
+            "enable-shared-internet-access is only effective when private network is enabled."
+        )
+
+    if wants_private_network and not has_vpc_id:
+        raise ValueError(
+            "vpc-id is required when private network is enabled (private/both)."
+        )
+
+    if not wants_private_network and enable_public_network is False:
+        raise ValueError(
+            "At least one network must be enabled. Enable public network or configure private network."
+        )
+
+    should_send_network_configuration = (
+        wants_private_network or enable_public_network is False
+    )
+    if not should_send_network_configuration:
+        return None
+
+    vpc = None
+    if wants_private_network:
+        subs = [s.strip() for s in (subnet_ids or "").split(",") if s.strip()] or None
+        vpc = rt.NetworkVpcForCreateRuntime(
+            vpc_id=(vpc_id or "").strip(),
+            subnet_ids=subs,
+            enable_shared_internet_access=(
+                True if enable_shared_internet_access else None
+            ),
+        )
+
+    return rt.NetworkForCreateRuntime(
+        vpc_configuration=vpc,
+        enable_private_network=wants_private_network,
+        enable_public_network=enable_public_network,
+    )
+
+
 @runtime_app.command("create")
 def create_runtime_command(
     name: str = typer.Option(..., "--name", help="Runtime name"),
@@ -71,7 +127,14 @@ def create_runtime_command(
         False, "--enable-private-network", help="Enable private network"
     ),
     enable_public_network: bool = typer.Option(
-        True, "--enable-public-network", help="Enable public network"
+        True,
+        "--enable-public-network/--no-enable-public-network",
+        help="Enable public network",
+    ),
+    enable_shared_internet_access: bool = typer.Option(
+        False,
+        "--enable-shared-internet-access",
+        help="Enable shared internet egress for private network (effective for private/both)",
     ),
     api_key_name: Optional[str] = typer.Option(
         None, "--apikey-name", help="API key name"
@@ -133,18 +196,13 @@ def create_runtime_command(
                 )
 
             network = None
-            if vpc_id or enable_private_network or enable_public_network:
-                vpc = None
-                if vpc_id:
-                    subs = [
-                        s.strip() for s in (subnet_ids or "").split(",") if s.strip()
-                    ] or None
-                    vpc = rt.NetworkVpcForCreateRuntime(vpc_id=vpc_id, subnet_ids=subs)
-                network = rt.NetworkForCreateRuntime(
-                    vpc_configuration=vpc,
-                    enable_private_network=enable_private_network,
-                    enable_public_network=enable_public_network,
-                )
+            network = _build_network_for_create_runtime(
+                vpc_id=vpc_id,
+                subnet_ids=subnet_ids,
+                enable_private_network=enable_private_network,
+                enable_public_network=enable_public_network,
+                enable_shared_internet_access=enable_shared_internet_access,
+            )
 
             envs = None
             if envs_json:

agentkit/toolkit/config/config_handler.py

@@ -110,6 +110,7 @@ def collect_cli_params(
         runtime_network_mode: Optional[str],
         runtime_vpc_id: Optional[str],
         runtime_subnet_ids: Optional[List[str]],
+        runtime_enable_shared_internet_access: Optional[bool],
     ) -> Dict[str, Any]:
         """Collect all CLI parameters.
 
@@ -204,6 +205,10 @@ def collect_cli_params(
             runtime_network["subnet_ids"] = ConfigParamHandler.parse_id_list(
                 runtime_subnet_ids
             )
+        if runtime_enable_shared_internet_access is not None:
+            runtime_network["enable_shared_internet_access"] = (
+                runtime_enable_shared_internet_access
+            )
         if runtime_network:
             strategy_params["runtime_network"] = runtime_network
         if runtime_auth_type is not None:

agentkit/toolkit/config/strategy_configs.py

@@ -323,7 +323,7 @@ class HybridStrategyConfig(AutoSerializableMixin):
         metadata={
             "hidden": True,
             "description": "Runtime network configuration (advanced, CreateRuntime only)",
-            "examples": "{mode: private, vpc_id: vpc-xxx, subnet_ids: [subnet-aaa, subnet-bbb]}",
+            "examples": "{mode: private, vpc_id: vpc-xxx, subnet_ids: [subnet-aaa, subnet-bbb], enable_shared_internet_access: true}",
         },
     )
     _config_metadata = {
@@ -588,7 +588,7 @@ class CloudStrategyConfig(AutoSerializableMixin):
         metadata={
             "hidden": True,
             "description": "Runtime network configuration (advanced, CreateRuntime only)",
-            "examples": "{mode: private, vpc_id: vpc-xxx, subnet_ids: [subnet-aaa, subnet-bbb]}",
+            "examples": "{mode: private, vpc_id: vpc-xxx, subnet_ids: [subnet-aaa, subnet-bbb], enable_shared_internet_access: true}",
         },
     )
 

agentkit/toolkit/runners/ve_agentkit.py

@@ -632,6 +632,9 @@ def _build_network_config_for_create(
         mode = runtime_network.get("mode")
         vpc_id = runtime_network.get("vpc_id")
         subnet_ids = runtime_network.get("subnet_ids")
+        enable_shared_internet_access_raw = runtime_network.get(
+            "enable_shared_internet_access"
+        )
 
         # Convenience: if vpc_id is provided without an explicit mode, assume private.
         if mode is None and vpc_id:
@@ -652,6 +655,30 @@ def _build_network_config_for_create(
         enable_public = mode in {"public", "both"}
         enable_private = mode in {"private", "both"}
 
+        enable_shared_internet_access: Optional[bool] = None
+        if enable_shared_internet_access_raw is not None:
+            if isinstance(enable_shared_internet_access_raw, bool):
+                enable_shared_internet_access = enable_shared_internet_access_raw
+            elif isinstance(enable_shared_internet_access_raw, (int, float)):
+                enable_shared_internet_access = bool(enable_shared_internet_access_raw)
+            else:
+                raw_str = str(enable_shared_internet_access_raw).strip().lower()
+                if raw_str in {"true", "1", "yes", "y"}:
+                    enable_shared_internet_access = True
+                elif raw_str in {"false", "0", "no", "n"}:
+                    enable_shared_internet_access = False
+                else:
+                    raise ValueError(
+                        "Invalid runtime_network.enable_shared_internet_access. "
+                        "Valid values: true/false."
+                    )
+
+        if enable_shared_internet_access and not enable_private:
+            raise ValueError(
+                "runtime_network.enable_shared_internet_access is only effective when "
+                "runtime_network.mode is private/both."
+            )
+
         vpc_configuration = None
         if enable_private:
             vpc_id_str = str(vpc_id or "").strip()
@@ -671,6 +698,9 @@ def _build_network_config_for_create(
             vpc_configuration = runtime_types.NetworkVpcForCreateRuntime(
                 vpc_id=vpc_id_str,
                 subnet_ids=parsed_subnet_ids,
+                enable_shared_internet_access=(
+                    True if enable_shared_internet_access else None
+                ),
             )
 
         return runtime_types.NetworkForCreateRuntime(

agentkit/version.py

@@ -12,4 +12,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-VERSION = "0.4.4"
+VERSION = "0.4.5"

docs/content/2.agentkit-cli/2.commands.md

@@ -537,7 +537,8 @@ launch_types:
 agentkit config \
   --runtime-network-mode private \
   --runtime-vpc-id vpc-xxxxxxxx \
-  --runtime-subnet-id subnet-aaaaaaaa
+  --runtime-subnet-id subnet-aaaaaaaa \
+  --runtime-enable-shared-internet-access
 ```
 
 **YAML 配置格式**（`agentkit.yaml`）：
@@ -548,6 +549,7 @@ launch_types:
     runtime_network:
       mode: private            # public | private | both
       vpc_id: vpc-xxxxxxxx     # private/both 必填
+      enable_shared_internet_access: true  # 仅对 private/both 生效
       subnet_ids:
         - subnet-aaaaaaaa
 ```
@@ -557,6 +559,10 @@ launch_types:
 - `private`：仅私网访问（需要 `vpc_id`）
 - `both`：同时开启公网与私网（需要 `vpc_id`）
 
+`enable_shared_internet_access` 说明：
+- 仅当 `mode` 为 `private` 或 `both` 时生效；开启后 Runtime 将使用平台提供的共享公网出口访问公网
+- 若 `mode=public` 且开启该开关，AgentKit 会报错以避免“看似配置但实际不生效”的误用
+
 ### 控制选项
 
 | 选项 | 说明 |
@@ -1826,4 +1832,4 @@ agentkit status
 
 - 📖 [配置文件说明](./3.configurations.md) - 深入了解每个配置项
 - 🚀 [快速开始](../1.introduction/3.quickstart.md) - 跟随教程实践
-- ❓ [问题排查](../1.introduction/4.troubleshooting.md) - 更多疑难问题解答
+- ❓ [问题排查](../1.introduction/4.troubleshooting.md) - 更多疑难问题解答

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentkit-sdk-python"
-version = "0.4.4"
+version = "0.4.5"
 description = "Python SDK for transforming any AI agent into a production-ready application. Framework-agnostic primitives for runtime, memory, authentication, and tools with volcengine-managed infrastructure."
 readme = "README.md"
 requires-python = ">=3.10"

tests/toolkit/cli/test_cli_runtime_network_config.py

@@ -0,0 +1,74 @@
+import pytest
+
+
+def test_build_network_none_when_no_user_intent():
+    from agentkit.toolkit.cli.cli_runtime import _build_network_for_create_runtime
+
+    network = _build_network_for_create_runtime(
+        vpc_id=None,
+        subnet_ids=None,
+        enable_private_network=False,
+        enable_public_network=True,
+        enable_shared_internet_access=False,
+    )
+    assert network is None
+
+
+def test_build_network_private_requires_vpc_id():
+    from agentkit.toolkit.cli.cli_runtime import _build_network_for_create_runtime
+
+    with pytest.raises(ValueError):
+        _build_network_for_create_runtime(
+            vpc_id=None,
+            subnet_ids=None,
+            enable_private_network=True,
+            enable_public_network=True,
+            enable_shared_internet_access=False,
+        )
+
+
+def test_build_network_disable_public_requires_private():
+    from agentkit.toolkit.cli.cli_runtime import _build_network_for_create_runtime
+
+    with pytest.raises(ValueError):
+        _build_network_for_create_runtime(
+            vpc_id=None,
+            subnet_ids=None,
+            enable_private_network=False,
+            enable_public_network=False,
+            enable_shared_internet_access=False,
+        )
+
+
+def test_build_network_vpc_id_implies_private_enabled():
+    from agentkit.toolkit.cli.cli_runtime import _build_network_for_create_runtime
+
+    network = _build_network_for_create_runtime(
+        vpc_id="vpc-123",
+        subnet_ids=None,
+        enable_private_network=False,
+        enable_public_network=True,
+        enable_shared_internet_access=False,
+    )
+    assert network is not None
+    assert network.enable_private_network is True
+    assert network.enable_public_network is True
+    assert network.vpc_configuration is not None
+    assert network.vpc_configuration.vpc_id == "vpc-123"
+
+
+def test_build_network_shared_internet_access_sets_vpc_field():
+    from agentkit.toolkit.cli.cli_runtime import _build_network_for_create_runtime
+
+    network = _build_network_for_create_runtime(
+        vpc_id="vpc-123",
+        subnet_ids="subnet-1,subnet-2",
+        enable_private_network=True,
+        enable_public_network=False,
+        enable_shared_internet_access=True,
+    )
+    assert network is not None
+    assert network.enable_private_network is True
+    assert network.enable_public_network is False
+    assert network.vpc_configuration is not None
+    assert network.vpc_configuration.enable_shared_internet_access is True