文档中心

API 网关

最佳实践

基于 API 网关访问 VCI Agent Sandbox

API 网关支持对接 VCI Agent Sandbox，将容器集群 VCI 实例下的 Agent Sandbox Pod 抽象为一个 Upstream，作为网关的路由后端。适用于业务采用 Agent Sandbox 部署，希望通过网关按 Sandbox ID 动态发布业务的场景。本文为您介绍如何通过 API 网关访问 VCI Agent Sandbox 。

说明

本文提供 Agent Sandbox 数据面转发（比如转发请求到 Sandbox 内执行），如果 Agent Sandbox 的控制面转发（比如创建 Sandbox 等）也需要接入 API 网关，您需要创建对应的容器服务类型 Upstream、服务和路由，请参见创建容器服务类型 Upstream、创建服务和创建路由。

前提条件

已创建 VCI 业务所需的集群且已安装 VCI Agent Sandbox。详细操作，请参见在 VPC-CNI 网络模型集群中使用 VCI、在 Flannel 网络模型集群中使用 VCI 和安装指南。

已创建 API 网关实例，具体操作可参见创建实例。因 API 网关实例 IP 在实例升级或者重启时会发生变化，暂时无法固定，当 VCI Agent Sandbox 启用 Network Policy 对出入向网络限制时，建议您创建 API 网关实例选择较小的子网地址空间（避免 IP 浪费和过渡放权），同时在 Network Policy 网络配置中放行 API 网关实例的子网。参考配置如下，关于 Network Policy 更多说明，请参见使用 NetworkPolicy 实现网络访问控制。

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: allow-ingress-from-cidr
namespace: default
spec:
podSelector:
matchLabels:
app: web # 匹配标签 app = web 的 Pod（被访问对象）
policyTypes:
- Ingress # 管控入站流量
ingress:
- from:
- ipBlock:
cidr: 192.**.**.**/**
# 允许来源网段，尽可能小，配置为 APIG 实例子网
# 如需排除段可以加 except:
# except:
# - 192.**.**.**/**
ports:
- protocol: TCP
port: 49983 # envd 端口
- protocol: TCP
port: 49999 # code interpreter 端口

使用限制

API 网关实例与容器服务集群必须处于同一 VPC 下。

操作步骤

步骤一：导入 Agent Sandbox 所在容器集群

在顶部导航栏，选择目标地域。

在实例管理下拉框选择目标实例后，单击容器集群导入。

在集群列表页面，单击导入集群。

在导入集群页面，按要求配置信息。详情请参见导入容器集群。

配置项	说明
K8S 集群	选择具体要对接的集群。本示例选择已有集群 smart-llm-router。说明仅支持选择与网关实例处于同一 VPC 下的集群。仅支持选择状态为运行中的集群。对于 Flannel 集群，所选集群的 Pod CIDR 必须与创建网关实例时选择的 Pod CIDR 网段一致。
路由同步	配置是否开启路由同步功能。开启路由同步后，API 网关会自动监听容器的路由规则 Ingress 资源的变化，并生效 Ingress 资源中的相关配置，将 Ingress 资源转义为服务、自定义域名、路由、Upstream 等资源合并至当前网关。详细介绍请参见 Ingress 路由同步。

单击确定，完成集群导入。

步骤二：创建 VCI Agent Sandbox 类型 Upstream

在左侧导航栏单击 Upstream 列表。

在 Upstream 列表页面，单击创建 Upstream。

在创建 Upstream 页面，按要求填写参数信息。

基本信息

配置项
说明
Upstream 名称
自定义 Upstream 名称，同一实例下的 Upstream 名称唯一。本示例配置为 agent-sandbox。

后端配置

配置项	说明
后端服务	选择 Upstream 对接的后端服务类型。本示例选择 VCI Agent Sandbox。
监听范围	配置监听范围。全部 Sandbox：覆盖所选集群内全部 Sandbox。按 Label 选择：需输入 Sandbox Label 的 Key 与 Value，支持使用表格编辑和使用 JSON 格式编辑。

单击确定，完成配置。

步骤三：创建服务

在左侧导航栏单击服务列表（域名）。在服务列表页面，单击创建服务。

在创建服务对话框，设置服务参数。

配置项	说明
所属实例	服务属于实例级别的资源。
服务名称	自定义服务名称。同一实例下服务名称唯一。本示例配置为 agent-sandbox-service。
备注	输入备注信息。

单击确定，完成创建服务。

步骤四：创建路由

在左侧导航栏选择服务列表（域名），在服务列表页面，单击目标服务操作列下的创建路由。

在创建路由页面，配置路由信息。此处仅列出 Upsteam 流量分发配置，详情请参见创建路由。

配置项	说明
后端类型	选择接入的 Upstream 类型。本示例选择 VCI Agent Sandbox。
选择 Upstream	选择具体要对接的 Upstream。选择创建的 VCI Agent Sandbox 类型的 Upstream。
权重	配置当前 Upstream 的流量权重。整数形式，取值范围为 1～1000。说明系统会根据 Upstream 配置的权重总值和各 Upstream 的权重占比，按比例显示流量划分，百分比数字精确到两位小数。

单击确定，完成路由创建。

步骤五：获取服务默认域名进行 SDK 引用

在左侧导航栏单击服务列表（域名）。

单击目标服务名称，在服务概述页签获取访问域名。

在客户端引用 SDK 时增加以下环境变量，其中的域名替换为获取的服务默认域名。详情请参见 SDK 开发指南。

os.environ["E2B_SANDBOX_URL"] = "s****.apigateway-cn-beijing.volceapi.com"

结果验证

结果验证前您需要创建模版，具体操作请参见创建模版。

创建sandbox_demo.py文件，内容如下。本示例run_sandbox_demo函数的入参值为default--code-interpreter-template，其中default为容器服务集群中的命名空间，code-interpreter-template为模版名称。

import os
from e2b_code_interpreter import Sandbox

# 火山引擎API网关环境变量配置
os.environ["E2B_API_KEY"] = "c03****"
os.environ["E2B_API_URL"] = "http://suq****.apigateway-cn-beijing.volceapi.com"# 控制面 API 网关根据实际情况配置，不强依赖 APIG
os.environ["E2B_SANDBOX_URL"] = "http://sih8****.apigateway-cn-beijing.volceapi.com"

def run_sandbox_demo(template_name: str):
sandbox = None
try:
print("开始创建沙盒实例")
sandbox = Sandbox.create(
template=template_name,
)
print(f"沙盒信息：{sandbox.get_info()}")

print("执行shell命令：echo hello from sandbox")
result = sandbox.commands.run("echo hello from sandbox")
print("标准输出：", result.stdout.strip())

except Exception as e:
print(f"沙盒运行异常：{e}")
finally:
if sandbox is not None:
print("销毁沙盒资源")
sandbox.kill()

if __name__ == "__main__":
run_sandbox_demo("default--code-interpreter-template")# 此处入参格式为 {容器服务集群中的命名空间}--{模板名称}

进入文件所在路径执行如下命令。

python sandbox_demo.py

预期返回结果如下：

开始创建沙盒实例
沙盒信息:SandboxInfo(sandbox_id='default--sbx-19****', template_id='default--code-interpreter-template', name='', 'metadata={'agents.xk8s.io/controller-first-observed-at'}
执行shell命令:echo hellofrom sandbox
标准输出:hello from sandbox
销毁沙盒资源

最近更新时间：2026.09.15 17:08:50

这个页面对您有帮助吗？

有用

无用

配置项	说明
Upstream 名称	自定义 Upstream 名称，同一实例下的 Upstream 名称唯一。本示例配置为 agent-sandbox。