VeADK Agent 一键容器化部署，万字长文带你实战演练

点击上方👆蓝字关注我们！

背景

近年来，人工智能技术的发展正从模型为中心转向以应用为中心，智能体（Agent）作为 AI 应用的核心载体，其落地部署需求日益迫切。而随着 AI 应用向生产环境迁移，以 Kubernetes 为核心的云原生基础设施成为很多企业的默认选择，为 Agent 应用提供标准化、可扩展且具备成本效益的运行时环境势在必行。

根据 CNCF 最新发布的年度云原生调查：

Kubernetes 已从容器编排工具，发展为现代基础设施的核心，包括 AI 领域。在容器用户中，82% 已在生产环境使用 Kubernetes，66% 的 AI 采用者用它来扩展推理任务。Kubernetes 不再是小众工具，而是支撑规模、可靠性和 AI 系统的基础层。 —— CNCF Annual Cloud Native Survey The infrastructure of AI’s future

火山引擎的 Agent 开发套件（VeADK/AgentKit）目前已具备将 Agent 应用一键部署至函数服务（veFaaS）的能力。该路径为开发者提供了快速验证和轻量级部署的便利。然而，当 Agent 应用从实验阶段走向生产成熟阶段，其对环境的要求也随之提升。生产级应用通常需要更强的环境控制力、更复杂的依赖管理、更可靠的运行保障以及更精细的成本控制。因此，将 Agent 应用的部署目标从 veFaaS 延伸至火山引擎容器服务（VKE），是满足其生产化需求的一个可选的方向。

VKE 作为一个生产级的 Kubernetes 托管服务，能够提供：

• 安全可靠的环境：通过 IAM for Service Accounts （IRSA） 等机制实现细粒度的权限管控，避免敏感密钥硬编码。
• 极致的弹性伸缩：借助水平 Pod 自动扩缩容（HPA），根据负载自动调整资源，实现成本与性能的最佳平衡。
• 全面的可观测性：无缝集成日志服务、监控告警等系统，提供端到端的应用健康度洞察。
• 开放的云原生生态：与 API 网关、持续集成与持续部署（CI/CD）等工具链深度整合，加速应用交付与迭代。

本文旨在介绍一套将 VeADK Agent 部署至 VKE 的标准化路径，为 AI 应用提供一个真正意义上的生产级云原生托管方案，实现从开发、部署到运维的全生命周期高效管理。

1. 创建 VKE 托管版集群及节点池。
2. 使用 IRSA 机制，安全地将应用与火山引擎的其他云服务 API 连接。
3. 使用 Dockerfile 将应用容器化，并将其推送到火山引擎容器镜像服务（CR）。
4. 编写并应用 Deployment 和 Service 的 Kubernetes 声明式配置。
5. 使用水平 Pod 自动扩缩容（HPA）配置应用的弹性伸缩。
6. 使用火山引擎 API 网关将应用发布至公网。
7. 日志查看与监控观测。

VeADK Agent 容器化部署实践

环境准备

在开始操作前，请完成以下准备工作。

火山引擎账号与访问密钥

你需要一个已完成实名认证的火山引擎账号，并创建访问密钥（Access Key），用于本地与云端资源的身份验证。

• 注册账号：若无账号，请前往火山引擎官网 注册并完成实名认证。
• 创建访问密钥（AK/SK）：

a. 登录火山引擎控制台。

b. 进入访问控制服务。

c. 在左侧导航栏选择用户，找到你的 IAM 用户（或新建用户）。

d. 点击用户名进入详情页，选择密钥管理标签页。

e. 点击新建密钥，生成 Access Key ID（AK）和 Secret Access Key（SK）。

重要提示：AK/SK 代表你的账户权限，请妥善保管，避免泄露导致安全风险。

配置本地开发环境

安装以下命令行工具，用于操作火山引擎 VKE 及 Kubernetes 集群。

• 安装 kubectl : kubectl 是与 Kubernetes 集群交互的标准命令行工具。请参考 Kubernetes 官方文档进行安装：https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/。
• 安装并配置火山引擎 CLI : 火山引擎 CLI 工具可以帮助你通过命令行管理云资源。

1. 安装 CLI : 请参考火山引擎 CLI 官方文档进行安装：https://www.volcengine.com/docs/83927/1184023?lang=zh。
2. 配置 CLI : 安装完成后，运行配置命令，并输入你之前创建的 AK/SK 和默认地域（例如 cn-beijing）。

  
volc configure  

根据提示依次输入 AK、SK、Region 和 Output 格式。

  
Access Key ID [****************YQ==]: YOUR\_ACCESS\_KEY  
Secret Access Key [****************NQ==]: YOUR\_SECRET\_KEY  
Region [cn-beijing]: cn-beijing  
Output [json]: json  

开通所需云服务

请确保在火山引擎控制台已激活以下服务：

• 容器服务（VKE）：用于部署与管理 AI 代理应用。
• 容器镜像服务（CR）：用于存储应用容器镜像。
• API 网关（APIG）：用于将服务公开至公网。
• 日志服务（TLS）：用于收集与分析应用日志。

安装项目依赖

安装 uv 包管理器：

  
# macOS / Linux（官方安装脚本）  
curl -LsSf https://astral.sh/uv/install.sh | sh  
  
# 或使用 Homebrew（macOS）  
brew install uv  

初始化项目依赖：

  
# 如果没有 `uv` 虚拟环境，可以使用命令先创建一个虚拟环境  
uv venv --python 3.12  
  
# 使用 `pyproject.toml` 管理依赖  
uv sync  
  
# 激活虚拟环境  
source .venv/bin/activate  

基础设施准备：创建 VKE 集群与节点

部署的第一步是搭建承载 Agent 应用的 Kubernetes 环境。

创建 VKE 托管版集群

首先，你需要创建一个 VKE 托管版集群作为 AI Agent 部署的基石。选择“托管版”可将 Kubernetes 控制面的管理工作（如扩缩容、升级和运维）交由火山引擎负责，使团队能更专注于业务应用。

1. 创建集群

在终端中，创建一个名为 vke-veadk 的集群

  
ve vke CreateCluster --body '{  
    "KubernetesVersion": "1.30",  
    "Name": "vke-veadk",  
    "DeleteProtectionEnabled": true,  
    "ProjectName": "default",  
    "ServicesConfig": {  
        "ServiceCidrsv4": [  
            "192.168.120.0/22"  
        ]  
    },  
    "ClusterConfig": {  
        "SubnetIds": [  
            "<subnet-1>",  
            "<subnet-2>",  
            "<subnet-3>"  
        ],  
        "ApiServerPublicAccessEnabled": true,  
        "ApiServerPublicAccessConfig": {  
            "PublicAccessNetworkConfig": {  
                "Bandwidth": 10,  
                "BillingType": 3  
            }  
        },  
        "ResourcePublicAccessDefaultEnabled": false  
    },  
    "PodsConfig": {  
        "PodNetworkMode": "VpcCniShared",  
        "VpcCniConfig": {  
            "SubnetIds": [  
                "<subnet-1>",  
                "<subnet-2>",  
                "<subnet-3>"  
            ]  
        }  
    },  
    "KubernetesConfig": {  
        "ControlPlaneConfig": {  
            "KubeApiServerConfig": {  
                "AdmissionPlugins": {  
                    "AlwaysPullImages": true  
                }  
            }  
        }  
    },  
    "MaintenanceWindowConfig": {  
        "Enabled": true,  
        "Duration": 4,  
        "WeeklyCycle": [  
            "Tuesday",  
            "Wednesday"  
        ],  
        "StartTime": "17:00:00Z"  
    },  
    "MonitoringConfig": {  
        "WorkspaceId": "<bbf418e8-***>",  
        "ComponentConfigs": [  
            {  
                "Name": "KubeApiServer",  
                "Enabled": true  
            },  
            {  
                "Name": "KubeScheduler",  
                "Enabled": true  
            },  
            {  
                "Name": "Etcd",  
                "Enabled": true  
            },  
            {  
                "Name": "ClusterAutoscaler",  
                "Enabled": true  
            }  
        ]  
    },  
    "LoggingConfig": {  
        "LogProjectId": "de71fc2e-***",  
        "LogSetups": [  
            {  
                "LogType": "KubeApiServer",  
                "Enabled": true  
            },  
            {  
                "LogType": "KubeScheduler",  
                "Enabled": true  
            },  
            {  
                "LogType": "KubeControllerManager",  
                "Enabled": false  
            },  
            {  
                "LogType": "Etcd",  
                "Enabled": true  
            },  
            {  
                "LogType": "ClusterAutoscaler",  
                "Enabled": false  
            }  
        ]  
    }  
}'  

说明：集群创建过程大约需要 5-10 分钟。请耐心等待。

2. 创建节点池

在集群内创建一个或多个节点池，用于运行 Agent 应用的工作负载。建议根据应用对计算、内存或 GPU 的需求，选择合适的 ECS 实例规格。

  
Plain Text  
ve vke CreateNodePool --body '{  
    "ClusterId": "<cd57q2***>",  
    "Name": "agent-nodes",  
    "KubernetesConfig": {  
        "Labels": [],  
        "Cordon": false,  
        "AutoSyncDisabled": false  
    },  
    "NodeConfig": {  
        "InstanceTypeIds": [  
            "ecs.g3il.xlarge",  
            "ecs.g3il.2xlarge",  
            "ecs.g3il.4xlarge"  
        ],  
        "ImageType": "",  
        "ImageId": "image-ybqi99s7yq8rx7mnk44b",  
        "SubnetIds": [  
            "<subnet-1>",  
            "<subnet-2>",  
            "<subnet-3>"  
        ],  
        "SystemVolume": {  
            "Size": 40,  
            "Type": "ESSD\_PL0"  
        },  
        "DataVolumes": [  
            {  
                "Size": 100,  
                "Type": "ESSD\_PL0"  
            }  
        ],  
        "Security": {  
            "SecurityStrategies": [  
                "Hids"  
            ],  
            "Login": {  
                "SshKeyPairName": "<key-***>"  
            }  
        },  
        "InstanceChargeType": "PostPaid",  
        "Period": 1,  
        "AutoRenew": true,  
        "AutoRenewPeriod": 1,  
        "AdditionalContainerStorageEnabled": true,  
        "HpcClusterIds": [],  
        "ProjectName": "default"  
    },  
    "AutoScaling": {  
        "DesiredReplicas": 3,  
        "SubnetPolicy": "ZoneBalance"  
    },  
    "Management": {  
        "Enabled": false  
    }  
}'  

3. 生成 kubeconfig 并连接 VKE 集群

  
Plain Text  
ve vke CreateKubeconfig --body '{  
    "ClusterId": "<cd57q2***>",  
    "Type": "Public"  
}'  

4. 连接 VKE 集群

集群创建成功后，需要配置 kubectl 以便能够连接并管理它。

步骤1 获取 kubeconfig：

  
ve vke ListKubeconfigs --body '{  
    "Filter": {  
        "ClusterIds": ["<cd57qavvv9l***>"],  
        "Types": ["Public"]  
    }  
}' | jq -r '.Result.Items[0].Kubeconfig'  

步骤2 在你的本地终端中，粘贴并执行该命令：

  
# 示例命令，请以你控制台实际生成的为准  
export KUBECONFIG=~/.kube/config\_vke\_adk-vke-cluster\_****  
kubectl config use-context adk-vke-cluster  

步骤3 执行完成后，运行以下命令验证是否已成功连接到集群：

  
kubectl get nodes  

如果能看到你创建的节点信息列表，说明连接已成功建立。从现在起，你的 kubectl 命令都将指向这个新的 VKE 集群。

开启安全围栏配置（IRSA）

为了保障云服务访问的安全性，本方案采用 IAM for Service Accounts （IRSA） 机制，避免在应用代码或容器镜像中硬编码或存储静态的访问密钥（AK/SK）。

IRSA 的核心机制是将 Kubernetes 的服务账号（ServiceAccount, KSA）与火山引擎的 IAM 角色进行绑定。当一个 Pod 被配置为使用此 KSA 启动时，VKE 会自动为其注入临时的、具有特定权限的安全凭证。这样，Pod 内的应用程序（即 Agent）便可通过标准 SDK 直接调用其被授权的云服务 API，无需任何手动密钥配置。

开启 IRSA 请参考 VKE 产品文档：https://www.volcengine.com/docs/6460/1324613?lang=zh。

5. 创建 IAM 角色

在 IAM 控制台，新建 OIDC 身份提供商类型的 IAM 角色，比如：agent_onvke。

6. 给角色授予所需要的权限

这里以方舟大模型权限为例：

7. 授权 VKE 集群内指定命名空间（NameSpace）下的服务账号（Service Account）

如 veadk-agent-sa，允许扮演上述创建的 IAM 角色。代码示例如下：

  
{  
    "Statement": [  
        {  
            "Effect": "Allow",  
            "Action": [  
                "sts:AssumeRoleWithOIDC"  
            ],  
            "Condition": {  
                "StringLike": {  
                    "oidc:aud": "sts.volcengine.com", // 固定值，OIDC 中的 Audience 值。  
                    "oidc:iss": "https://oidc-vke-cn-beijing.tos-cn-beijing.volces.com/ccog93vv********", // 配置为您的集群开启 IRSA 能力后控制台中显示的“供应商 URL”信息。  
                    "oidc:sub": "system:serviceaccount:oidc-ns-1:oidc-sa-1"// 需要满足格式：system:serviceaccount:{namespace}:{serviceaccount} ，其中{namespace}和{serviceaccount}是 Kubernetes 集群内目标 NameSpace 和 Service Account。  
                }  
            },  
            "Principal": {  
                "Federated": [  
                    "trn:iam::2100******:oidc-provider/vke-irsa-********"  
                ]  
            }  
        }  
    ]  
}  

8. 在 VKE 集群创建 Service Account

VKE SA 与 IAM 角色关联，示例文件内容如下：

  
---  
apiVersion:v1  
kind:ServiceAccount  
metadata:  
name:oidc-sa-1  
namespace:oidc-ns-1# Service Account 名称。与“步骤三”中配置的 Service Account 名称保持一致。  
annotations:  
    vke.volcengine.com/role-trn:trn:iam::2100******:role/podrole1234# 该 Service Account 关联的 IAM 角色 TRN（在访问控制的角色详情页面获取角色 TRN）。如果未配置该 Annotation 或配置的值不是一个合法的 IAM 角色 TRN，则使用该 Service Account 的 Pod 将不会被自动注入配置。  

9. 为 Pod 注入 IRSA 配置

示例内容如下：

  
apiVersion: v1  
kind:Pod  
metadata:  
name:pod-1# Pod 名称。  
namespace:oidc-ns-1# 与上方设置的 NameSpace 名称保持一致。  
spec:  
serviceAccountName:oidc-sa-1# 与上方设置的 Service Account 名称保持一致。  
volumes:# 为 Pod 设置服务账号令牌卷投影。更多信息，请见 Kubernetes 文档：https://kubernetes.io/zh-cn/docs/tasks/configure-pod-container/configure-service-account/#serviceaccount-token-volume-projection 。  
-name:irsa-oidc-token# 卷名称，与下方 volumeMounts 下的挂载卷名称保持一致。  
    projected:  
      defaultMode:420  
      sources:  
        -serviceAccountToken:  
            audience:sts.volcengine.com# 固定值，表示指定的 Audience 值。  
            expirationSeconds:3600# OIDC Token 有效期，单位为：秒。  
            path:token  
containers:  
    env:# Pod 中实现请求 AssumeRoleWithOIDC 所需的环境变量。  
      -name:VOLCENGINE\_OIDC\_ROLE\_TRN  
        value:<role\_trn>  
      -name:VOLCENGINE\_OIDC\_TOKEN\_FILE  
        value:/var/run/secrets/vke.volcengine.com/irsa-tokens/token# OIDC Token 挂载地址，与下方 volumeMounts 下的挂载地址保持一致。  
    image:cr-cn-beijing.volces.com/******:latest# 容器镜像地址和 Tag，请配置为您自己的镜像地址。  
    imagePullPolicy:IfNotPresent  
    name:c-test# 容器名称。  
    volumeMounts:  
      -name:irsa-oidc-token# 挂载卷名称，与上方 volumes 下的卷名称保持一致。  
        readOnly:true  
        mountPath:/var/run/secrets/vke.volcengine.com/irsa-tokens/token# OIDC Token 挂载地址。  

Agent 开发与本地验证

本方案以官方提供的 realtime\_voice 示例为基础，展示一个实时语音旅行规划 Agent 的开发与部署流程：https://github.com/bytedance/agentkit-samples/blob/main/02-use-cases/beginner/realtime\_voice/README.md。

  
agent = Agent(  
    name="voice\_assistant\_agent",  
    model=MODEL,  
    instruction=SYSTEM\_INSTRUCTION,  
  
)  
# Create run config with audio settings  
run\_config = RunConfig(  
    streaming\_mode=StreamingMode.BIDI,  
    speech\_config=types.SpeechConfig(  
        voice\_config=types.VoiceConfig(  
            prebuilt\_voice\_config=types.PrebuiltVoiceConfig(  
                voice\_name=VOICE\_NAME  
            )  
        )  
    ),  
    response\_modalities=["AUDIO"],  
    output\_audio\_transcription=types.AudioTranscriptionConfig(),  
    input\_audio\_transcription=types.AudioTranscriptionConfig(),  
)  

在部署到 VKE 之前，开发者可在本地环境中快速启动 Agent 服务，并通过浏览器客户端进行功能验证，确保核心逻辑无误：

  
cd realtime\_voice  
# 启动 Agent 服务  
uv run agent.py  
# 服务将监听 http://0.0.0.0:8000  
  
# 新开客户端  
# 在浏览器中打开 client/interface.html，客户端将自动连接到 WebSocket 服务器。  

应用容器化与镜像推送

10. 使用 Docker 将应用容器化

为了在 Kubernetes 中运行，Agent 应用需被打包成一个标准的容器镜像。

在项目根目录下，创建 Dockerfile 文件：

  
cat <<'EOF' > Dockerfile  
# Support custom base image  
FROM agentkit-cn-beijing.cr.volces.com/base/py-simple:python3.12-bookworm-slim-latest  
  
ENV UV\_SYSTEM\_PYTHON=1 UV\_COMPILE\_BYTECODE=1 PYTHONUNBUFFERED=1 DOCKER\_CONTAINER=1  
  
COPY requirements.txt requirements.txt  
  
RUN uv pip install -r requirements.txt  
  
EXPOSE 8000  
  
WORKDIR /app  
  
# Copy entire project  
COPY . .  
  
CMD ["python", "-m", "agent"]  
EOF  

11. 构建镜像并推送至火山引擎 CR

拥有 Dockerfile 之后，我们就可以构建镜像并将其推送到火山引擎容器镜像服务 （CR） 了。

11.1 准备 CR 实例和命名空间

  
ve cr --body '{}'  

11.2 登录并推送镜像

现在，回到你的本地终端，执行以下步骤。

• 登录到 CR 实例：使用 docker login 命令。你需要提供用户名、实例访问域和之前设置的密码。

• 用户名：格式为 <火山引擎账号名>@<UserID>。

• 访问域：格式为 <实例名>-<地域>.cr.volces.com。

  
# 请替换为你的实际信息  
docker login --username=<你的火山引擎用户名@UserID> <你的实例访问域>  

当提示输入密码时，输入你在 CR 控制台设置的实例访问凭证。看到 Login Succeeded 表示登录成功。

• 为镜像打标签（Tag） : docker build 命令会先在本地构建镜像，-t 参数则为它打上一个符合 CR 仓库地址格式的标签。 完整的镜像地址格式为：<访问域>/<命名空间>/<镜像名>:<版本号>

  
# 请替换为你的实际信息  
docker build --platform linux/amd64 -t realtime\_voice:202512241645 .  
docker tag realtime\_voice:202512241645 wangyue-cn-beijing.cr.volces.com/agentkit/realtime\_voice:202512241645  

• 推送镜像 ：构建成功后，使用 docker push 命令将本地镜像推送到远端的 CR 仓库。

  
docker push wangyue-cn-beijing.cr.volces.com/agentkit/realtime\_voice:202512241645  

12. 编写 Kubernetes Deployment 和 Service

现在，我们将创建一个名为 deployment.yaml 的文件，它包含两个核心的 Kubernetes 对象：

• Deployment : 定义了我们希望应用如何运行的蓝图。它管理着 Pod 的副本数量、容器镜像、资源请求/限制、环境变量等。
• Service : 定义了如何将我们的应用（一组 Pod）作为一个稳定的网络服务暴露出来，无论是在集群内部还是外部。

在项目根目录下，创建 deployment.yaml 文件，并填入以下内容。

重要：请务必将 image 字段中的镜像地址替换为你自己刚刚推送到 CR 的镜像地址！

  
apiVersion: apps/v1  
kind:Deployment  
metadata:  
name:veadk-agent  
spec:  
replicas:1  
selector:  
    matchLabels:  
      app:veadk-agent  
template:  
    metadata:  
      labels:  
        app:veadk-agent  
    spec:  
      # Assign the Kubernetes Service Account for Workload Identity  
      serviceAccountName:veadk-agent-sa  
      volumes:# 为 Pod 设置服务账号令牌卷投影。更多信息，请见 Kubernetes 文档：https://kubernetes.io/zh-cn/docs/tasks/configure-pod-container/configure-service-account/#serviceaccount-token-volume-projection 。  
        -name:irsa-oidc-token# 卷名称，与下方 volumeMounts 下的挂载卷名称保持一致。  
          projected:  
            defaultMode:420  
            sources:  
              -serviceAccountToken:  
                  audience:sts.volcengine.com# 固定值，表示指定的 Audience 值。  
                  expirationSeconds:3600# OIDC Token 有效期，单位为：秒。  
                  path:token  
      containers:  
      -name:veadk-agent  
        imagePullPolicy:Always  
        # The path to the container image in Artifact Registry  
        # image: ${REGISTRY}-${REGION}.cr.volces.com/${REGISTRY\_NS}/${REGISTRY\_REPO}:latest  
        # wangyue-cn-beijing.cr.volces.com/agentkit/realtime\_voice:202512231745  
        image:<registry>-beijing.cr.volces.com/agentkit/realtime\_voice:202512252045  
        # Define the resources for GKE Autopilot to provision  
        resources:  
          limits:  
            memory:"1Gi"  
            cpu:"1000m"  
            ephemeral-storage:"512Mi"  
          requests:  
            memory:"1Gi"  
            cpu:"1000m"  
            ephemeral-storage:"512Mi"  
        ports:  
        -containerPort:8000  
        volumeMounts:  
          -name:irsa-oidc-token# 挂载卷名称，与上方 volumes 下的卷名称保持一致。  
            readOnly:true  
            mountPath:/var/run/secrets/vke.volcengine.com/irsa-tokens/token# OIDC Token 挂载地址。  
        # Environment variables passed to the application  
        env:  
        -name:PORT  
          value:"8000"  
        -name:DEPLOY\_VKE  
          value:"true"  
        -name:MODEL  
          value:doubao\_realtime\_voice\_model  
        -name:MODEL\_REALTIME\_API\_KEY  
          value:${MODEL\_REALTIME\_API\_KEY}  
        -name:MODEL\_REALTIME\_APP\_ID  
          value:${MODEL\_REALTIME\_APP\_ID}  
        -name:VOLCENGINE\_OIDC\_ROLE\_TRN  
          value:trn:iam::2100390175:role/agent\_onvke  
        -name:VOLCENGINE\_OIDC\_TOKEN\_FILE  
          value:/var/run/secrets/vke.volcengine.com/irsa-tokens/token# OIDC Token 挂载地址，与下方 volumeMounts 下的挂载地址保持一致。  
---  
apiVersion:v1  
kind:Service  
metadata:  
name:veadk-agent  
spec:  
selector:  
    app:veadk-agent  
ports:  
-name:rule  
    protocol:TCP  
    port:80  
    targetPort:8000  
type:ClusterIP  

将应用部署至 VKE

所有配置文件都已就绪，现在我们可以将 AI 代理应用正式部署到 VKE 集群中。我们将使用 kubectl 将配置应用到集群，并监控部署状态，确保代理程序能够顺利启动。

13. 应用部署配置

在你的本地终端，也就是项目根目录下，执行以下命令：

  
kubectl apply -f deployment.yaml  

这个 kubectl apply 命令会将 deployment.yaml 文件的内容发送给 Kubernetes API Server。API Server 读取文件后，会开始协调创建其中定义的 Deployment 和 Service 资源。

14. 监控 Pod 启动状态

部署指令发出后，我们可以实时观察 Pod 的启动过程，以确认一切正常。

  
# 使用 --watch 参数来持续监控带有 app=adk-agent 标签的 Pod  
kubectl get pods -l=app=veadk-agent --watch  

你将会看到 Pod 经历几个阶段：

• Pending: 集群已经接收 Pod 的创建请求，但尚未开始创建容器，可能正在等待节点资源或调度。
• ContainerCreating: VKE 节点正在从你的火山引擎 CR 仓库拉取容器镜像，并准备启动容器。
• Running: 成功！容器已经启动，并且通过了健康检查，你的 AI 代理应用现在正在运行中。

当看到 Pod 状态变为 Running 后，你可以按下 Ctrl+C 来停止监控，返回到命令行提示符。

配置弹性伸缩

HPA (Horizontal Pod Autoscaler)：为 veADK Agent Deployment 配置 HPA，基于 CPU 和内存使用率自动增减 Pod 数量。如下 HPA 策略，通过水平扩容 Pod，确保 CPU 整理利用率维持在 50% 以内。

  
# Configures the HorizontalPodAutoscaler (HPA) to automatically scale  
# the number of running agent pods up or down based on CPU utilization  
# to handle varying traffic loads.  
  
apiVersion:autoscaling/v1  
kind:HorizontalPodAutoscaler  
metadata:  
name:veadk-agent-hpa  
spec:  
scaleTargetRef:  
    apiVersion:apps/v1  
    kind:Deployment  
    name:veadk-agent  
minReplicas:1  
maxReplicas:5  
targetCPUUtilizationPercentage:50  

验证 HPA 策略已生效

  
kubectl get hpa  
NAME              REFERENCE                TARGETS   MINPODS   MAXPODS   REPLICAS   AGE  
veadk-agent-hpa   Deployment/veadk-agent   0%/50%    1         5         1          35s  

通过 API 网关暴露服务并进行交互

我们的代理应用已经在集群内部成功运行，但要从外部互联网访问它，我们还需要一步——创建一个 API 网关配置 Ingress 规则。APIG Ingress 基于火山引擎 API 网关（API Gateway，APIG） 提供托管的云原生网关功能，实现高可用、高扩展的 Ingress 流量管理方式。详细步骤参考官方文档。

15. 创建 APIGInstance

对接已有 APIG 实例，使用如下 YAML 配置，创建 APIGInstance 并对接已有 APIG 实例。

  
YAML  
apiVersion: loadbalancer.vke.volcengine.com/v1beta1  
kind: APIGInstance  
metadata:  
  name: apig-instance-demo # APIGInstance 资源名称  
spec:  
  id: gcq12c2tfm0mpjrej4*** # 已有 APIG 实例 ID  
  ingress:  
    enable: true# 是否开启 APIG 路由同步。取值：true（开启）、false（关闭）  
    enableAllIngressClasses: false# 是否同步所有的 IngressClasses，取值：true（开启）、false（关闭)  
    enableIngressWithoutIngressClass: false# 是否同步未关联 IngressClass 的 Ingress。取值：true（开启）、false（关闭）  
    ingressClasses: # 配置路由同步生效的 IngressClasses  
      - apig  
    enableAllNamespaces: false# 是否同步所有的命名空间中的 Ingress，取值：true（开启）、false（关闭）  
    watchNamespaces: # 配置路由同步生效的命名空间  
      - doc-demo  
      - default  

16. 创建 APIG Ingress 规则

基于路径转发，APIG Ingress 支持将相同域名、不同路径的访问，转发到不同的后端。示例 apig-ingress.yaml 代码如下：

  
YAML  
apiVersion: networking.k8s.io/v1  
kind: Ingress  
metadata:  
  name: veadk-voice-agent # 路由规则的名称  
  namespace: default  # 路由规则所属的命名空间  
  annotations:  
    ingress.vke.volcengine.com/apig-instance-name: veadk-agent-vke-apig # 指定 APIGInstance 资源名称  
spec:  
  ingressClassName: apig  
  rules:  
    - host: veadkrealtimevoiceagent.apigateway-cn-beijing.volceapi.com  # 需要对外提供访问的域名  
      http:  
        paths:  
        - pathType: Prefix # 路径匹配规则，默认为 Prefix（前缀匹配）  
          path: / # 请求匹配的路径  
          backend:  
            service:  
              name: veadk-agent # 需要对接的服务名称  
              port:  
                number: 80 # 需要对接服务的端口号  

17. 获取公网访问地址并测试

当 Ingress 规则被应用后，APIG Instance 控制器会自动创建转发规则，并将其与后端服务关联。

• 获取外部 IP 地址：

  
Bash  
ve apig GetGatewayService --body '{  
    "Id": "<sd5728khjptg***>"  
}'  

• 测试已部署的代理：

  
Plain Text  
# 需要编辑 client/interface.html，将其中的第 168 行的 ws://localhost:8000 修改为 agentkit.yaml 中生成的 runtime\_endpoint 字段  
# 在浏览器中打开 client/interface.html，客户端将自动连接到 WebSocket 服务器。        

日志&可观测

使用 kubectl 命令查看实时日志：

  
Bash  
# 首先找到你的 Pod 名称  
kubectl get pods -l=app=veadk-agent  
NAME                           READY   STATUS    RESTARTS   AGE  
veadk-agent-6bcdb5d996-l2wtq   1/1     Running   0          2d19h  
  
# 然后查看特定 Pod 的日志  
# 将 adk-agent-xxxx-yyyy 替换为你的实际 Pod 名称  
kubectl logs -f veadk-agent-6bcdb5d996-l2wtq  
2025-12-25 12:00:29 | DEBUG | live.py:211 - receive llm response: {'message\_type': 'SERVER\_FULL\_RESPONSE', 'event': 550, 'session\_id': 'b"b\'98484414-958e-4cfb-beeb-678a769ca872\'"', 'payload\_msg': {'content': '讲讲', 'question\_id': '34058118226449410', 'reply\_id': '34058118226450178'}, 'payload\_size': 85}  
2025-12-25 12:00:29 | DEBUG | live.py:211 - receive llm response: {'message\_type': 'SERVER\_FULL\_RESPONSE', 'event': 550, 'session\_id': 'b"b\'98484414-958e-4cfb-beeb-678a769ca872\'"', 'payload\_msg': {'content': '。', 'question\_id': '34058118226449410', 'reply\_id': '34058118226450178'}, 'payload\_size': 82}  

APIG 控制台观测网关请求：

总结

以上就是将 VeADK Agent 部署至 VKE 的实操介绍。对于企业级用户来说，将 Agent 应用部署至容器服务（VKE）有助于其走向生产成熟：不仅统一了 AI 应用的云原生技术栈，更在交付效率、性能、可靠性、成本与安全性等多个维度为用户带来了实质收益。研发团队也能够复用业界成熟的 Kubernetes 生态能力，将关注点从复杂的基础设施管理回归到 Agent 业务逻辑的创新本身。