随着大模型技术的飞速发展，AI Agent 正从概念走向生产。与传统的批处理任务或推理服务不同，Agent 工作负载呈现出独特的运行特征——间歇性活跃、极低延迟敏感、多轮会话状态持久化。然而，现有的 Kubernetes 调度体系主要面向批处理和长运行服务设计，难以有效应对这类"潮汐式"交互负载：空闲时资源白白占用，唤醒时又无法做到亚秒级响应，状态管理更是一大痛点。

AgentCube^[1] 正是为解决这一矛盾而生。作为 Volcano社区^[2]的子项目，AgentCube 专为 AI Agent 工作负载打造了专用的控制面与数据面，核心优势体现在四个方面：

• 极速启动—— 通过 Warm Pool （预热池）机制预先创建并暂停一批沙箱，当 Agent 请求到来时以 "Claim-and-Go" 的方式进行毫秒级分配，消除冷启动瓶颈。
• 高效调度 —— 借助 Volcano Agent Scheduler 的乐观并发控制与精简调度策略，大幅提升调度吞吐，并能与 Volcano 原有的 Batch Scheduler 无缝协作，确保 Agent 与传统批处理作业的统一调度与资源协调。
• 原生会话管理 —— 以 Session ID 为核心路由标识，会话到来时自动识别并路由请求至对应沙箱，并在沙箱休眠时自动唤醒，保障多轮交互的上下文连续性。
• 安全隔离 —— 为每个会话分配独立沙箱，确保计算、内存与文件系统的端到端隔离，防止跨租户数据泄露。同时支持以安全容器运行 Agent，借助安全运行时技术实现内核级强隔离。

本文将聚焦 AgentCube 在华为云 CCE（云容器引擎）上的实践，探讨如何将 AgentCube 的调度能力与 CCE 的基础设施深度结合，为 AI Agent 应用提供高效、稳定的云原生运行底座。关于AgentCube的原理可通过设计文档^[3]或往期文章^[4]了解。

  环境准备  

• 已经创建好了一个1.29或更高版本的CCE集群
• 确保本地安装的python版本>=3.11
• 安装SDK^[5] ： pip install agentcube_sdk

  安装 AgentCube 插件  

AgentCube目前已上架华为云 CCE 插件市场。可通过登录CCE控制台^[6]进入集群插件中心界面，找到AgentCube插件进行配置安装。

AgentCube主要组件：

• workloadmanager：管理AgentRuntime和CodeInterpreter的生命周期。
• agentcube-router：API 网关，代理客户端请求到沙箱实例。
• volcano-agent-scheduler：调度器组件，提供低延迟和高吞吐的负责调度。
• agent-sandbox-controller：管理AgentSandbox资源。

安装时需要设置如下参数：

• redis.addr：Redis的地址，必须配置。
• redis.password：Redis的密码，必须配置。
• agentSandbox.install：是否自动安装agent-sandbox。AgentCube插件运行时依赖 agent-sandbox^[7]，当参数配置为true时会自动安装。如果集群已手动安装了agent-sandbox，则可配置为false跳过安装。
• agentSandbox.extensions：是否启用agent-sandbox的extension controller。
• volcano.scheduler.enabled：是否安装volcano agent-scheduler调度器。

由于AgentCube运行时依赖Redis维护会话状态和索引，从稳定性和可扩展性考虑，建议购买和使用华为云分布式缓存服务 DCS^[8]。此外，如果要在集群外访问 AgentCube，可为workloadmanager和agentcube-router的Service绑定ELB Ingress。

  开始使用  

▍步骤一：环境变量设置

export WORKLOAD_MANAGER_URL="http://workloadmanager-addr:workloadmanager-port" 
export ROUTER_URL="http://agentcube-router-addr:agentcube-router-port"

其中workloadmanager-addr、workloadmanager-service-nodeport为workload-manager的访问地址和端口，agentcube-router-addr、agentcube-router-port为agentcube-router的访问地址和端口。

▍步骤二：使用CodeInterpreter

CodeInterpreter是AgentCube两大核心能力之一（另一个是AgentRuntime），是专为执行 LLM 生成的不可信代码而设计的受限运行时。通过收窄模板配置、内置 JWT 认证和预热池加速，在保障安全隔离的同时实现毫秒级启动，适用于代码解释器等沙箱执行场景。

部署CodeInterpreter

首先创建文件code-interpreter.yaml：

apiVersion: runtime.agentcube.volcano.sh/v1alpha1
kind: CodeInterpreter
metadata:
  name: my-codeinterpreter
  namespace: default
spec:
  template:
    # runtimeClassName: kata    # 若使用安全容器，则可配置runtimeClassName为kata或kuasar-vmm（需要有支持安全运行时的节点）
    image: swr.ap-southeast-3.myhuaweicloud.com/container/picod:latest    # 使用 PicoD 镜像，当前示例使用的镜像仅支持执行shell和python代码
    resources:
      requests:
        cpu: "100m"
        memory: "128Mi"
      limits:
        cpu: "500m"
        memory: "512Mi"
  sessionTimeout: "15m"      # 空闲 15 分钟后超时
  maxSessionDuration: "8h"   # 最大会话时长 8 小时
  warmPoolSize: 5    # 预热 5 个 Pod

执行部署：

kubectl apply -f code-interpreter.yaml

验证是否部署成功：

kubectl get codeinterpreter

部署完成后，等待一段时间执行kubectl get pods |grep my-codeinterpreter可以看到已经预热出了5个CodeInterpreter。

远程执行第一份代码

创建python脚本quickstart.py：

import os
from agentcube import CodeInterpreterClient

WORKLOAD_MANAGER_URL = os.getenv('WORKLOAD_MANAGER_URL', 'http://workloadmanager.agentcube.svc.cluster.local:8080')
ROUTER_URL = os.getenv('ROUTER_URL', 'http://agentcube-router.agentcube.svc.cluster.local:8080')

with CodeInterpreterClient(name="my-codeinterpreter", namespace="default") as client:
    result = client.run_code("python", "print('Hello from AgentCube!')")
    print(result)

上述python脚本会连接到上一步部署的CodeInterpreter，启动一个隔离的沙箱会话，向其发送一段待执行的 Python 代码片段，并打印输出结果。执行python quickstart.py开始运行，输出：

2026-06-05 15:25:22,584 | INFO | agentcube.code_interpreter | Creating new session...
2026-06-05 15:25:22,790 | INFO | agentcube.code_interpreter | Session created: 900923f4-4d1c-4383-ac6b-331c5ec83acb
Hello from AgentCube!

2026-06-05 15:25:22,921 | INFO | agentcube.code_interpreter | Deleting session 900923f4-4d1c-4383-ac6b-331c5ec83acb...

尝试在一个会话中连续执行代码

在步骤三中，我们创建的 CodeInterpreter 仅运行了单次代码便自动结束了会话。但在真实的业务场景中，我们往往需要处理多轮连续交互。接下来，我们将通过一个更具实战价值的进阶示例，来展示 AgentCube 的会话保持能力。

创建python脚本longtask.py：

import os
from agentcube import CodeInterpreterClient

WORKLOAD_MANAGER_URL = os.getenv('WORKLOAD_MANAGER_URL', 'http://workloadmanager.agentcube.svc.cluster.local:8080')
ROUTER_URL = os.getenv('ROUTER_URL', 'http://agentcube-router.agentcube.svc.cluster.local:8080')

def session_reuse_workflow():
    # 步骤 1：创建会话并写入数据
    print("step 1: Create a session and write initial data.")
    client1 = CodeInterpreterClient(
        name='my-codeinterpreter',
        namespace='default',
        workload_manager_url=WORKLOAD_MANAGER_URL,
        router_url=ROUTER_URL,
    )

    # 写入多个文件
    client1.write_file("100", "counter.txt")
    client1.write_file("[]", "results.json")

    session_id = client1.session_id
    print(f"session ID: {session_id}")
    print("The file system status has been saved.\n")

    # 注意：不调用 client1.stop()，让会话保持活跃

    # 步骤 2：复用会话，读取并处理数据
    print("step 2: Reusing sessions and processing data.")
    client2 = CodeInterpreterClient(
        name='my-codeinterpreter',
        namespace='default',
        workload_manager_url=WORKLOAD_MANAGER_URL,
        router_url=ROUTER_URL,
        session_id=session_id,  # 复用会话
    )

    code = """
import json
import time

# 读取计数器
with open('counter.txt') as f:
    counter = int(f.read().strip())
print(f"current count: {counter}")

# 增加计数
counter += 1
with open('counter.txt', 'w') as f:
    f.write(str(counter))

# 读取结果列表
with open('results.json') as f:
    results = json.load(f)

# 添加新结果
results.append({
    'timestamp': time.time(),
    'counter': counter
})

# 保存结果
with open('results.json', 'w') as f:
    json.dump(results, f, indent=2)

print(f"new count: {counter}")
print(f"result count: {len(results)}")
"""

    result = client2.run_code("python", code)
    print(f"{result}\n")

    # 步骤 3：查看文件系统状态
    print("step 3: Verifying the File System Statuses")
    files = client2.list_files(".")
    print(f"Files in session: {[f['name'] for f in files]}\n")

    # 清理会话
    client2.stop()
    print("session is deleted")

if __name__ == "__main__":
    session_reuse_workflow()

上述python脚本首先创建了一个会话，往CodeInterpreter中上传了两个文件counter.txt和results.json。然后并不立即关闭会话，而是使用第一次创建会话时返回的session_id（会话ID）再次创建了一个客户端并远程执行代码。执行python longtask.py开始运行，输出如下：

step 1: Create a session and write initial data.
2026-06-05 15:45:03,386 | INFO | agentcube.code_interpreter | Creating new session...
2026-06-05 15:45:03,775 | INFO | agentcube.code_interpreter | Session created: eda5f22f-ad7d-4d95-9adf-b74dbf015051
session ID: eda5f22f-ad7d-4d95-9adf-b74dbf015051
The file system status has been saved.

step 2: Reusing sessions and processing data.
2026-06-05 15:45:03,893 | INFO | agentcube.code_interpreter | Reusing existing session: eda5f22f-ad7d-4d95-9adf-b74dbf015051
current count: 100
new count: 101
result count: 1

step 3: Verifying the File System Statuses
Files in session: ['.bashrc', '.profile', 'counter.txt', 'picod', 'results.json', 'script_1780645503894.py']

2026-06-05 15:45:04,072 | INFO | agentcube.code_interpreter | Deleting session eda5f22f-ad7d-4d95-9adf-b74dbf015051...
session is deleted

可以看到3轮请求的session_id是相同的，说明 AgentCube 识别到了请求所属中的会话ID，将所有请求都代理到了同一个CodeInterpreter实例而非创建新的。且第2、3轮请求能够读取到第1轮请求上传的文件，说明这个CodeInterpreter实例并没有被销毁和重建，它的整个运行时状态——包括文件系统、内存中的变量、进程上下文等，都在请求之间完整保留。这正是 CodeInterpreter 区别于无状态函数调用的核心优势。

▍步骤三：使用AgentRuntime

有别于 CodeInterpreter，AgentRuntime 支持完整的 PodSpec 自定义，适用于对话、工具调用等常规 Agent 场景。

部署AgentRuntime

创建agent.py、requirements.txt文件，其中agent.py文件内容为官方提供的Agent示例代码^[9]，requirements.txt如下：

agentcube_sdk

使用如下Dockerfile制作Agent容器镜像，并将制作好的镜像上传华为云SWR。

FROM python:3.11-slim

WORKDIR /app

# 复制依赖文件
COPY requirements.txt .

# 安装 Python 依赖
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY agent.py /app/

# 暴露端口
EXPOSE8080

# 运行应用
CMD ["python", "/app/agent.py"]

创建文件agent-runtime.yaml：

apiVersion: runtime.agentcube.volcano.sh/v1alpha1
kind: AgentRuntime
metadata:
  name: my-agent-app
  namespace: default
spec:
  targetPort:
    - pathPrefix: "/"
      port: 8080
      protocol: "HTTP"
  podTemplate:
    labels:
      app: my-agent-app
    spec:
      schedulerName: default-scheduler    # 如果开启安装了volcano agent-scheduler调度器，可配置为agent-scheduler
      containers:
        - name: my-agent-app
          image: {{agent image}}    # 构建好并上传华为云SWR的Agent容器镜像
          env:
            - name: WORKLOAD_MANAGER_URL
              value: http://workloadmanager.agentcube.svc.cluster.local:8080
            - name: ROUTER_URL
              value: http://agentcube-router.agentcube.svc.cluster.local:8080
            - name: CODEINTERPRETER_NAME
              value: my-codeinterpreter
            - name: CODEINTERPRETER_NAMESPACE
              value: default
          readinessProbe:
            httpGet:
              path: /health
              port: 8080
            periodSeconds: 5
  sessionTimeout: "15m"             # 空闲 15 分钟后超时
  maxSessionDuration: "8h"          # 最大会话时长 8 小时
status: {}

执行部署:

kubectl apply -f agent-runtime.yaml

验证是否部署成功:

kubectl get agentruntime

输出:

NAME           AGE
my-agent-app   1m

说明部署成功，my-agent-app为我们创建的Agent的名字。

与Agent进行对话

创建python脚本chatToAgent.py：

from agentcube.agent_runtime import AgentRuntimeClient
import os
import time


ROUTER_URL = os.getenv('ROUTER_URL', 'http://agentcube-router.agentcube.svc.cluster.local:8080')

def test_conversation():
    # 第一轮对话
    agent_client1 = AgentRuntimeClient(
        agent_name='my-agent-app',
        namespace='default',
        router_url=ROUTER_URL,
        timeout=500,
        connect_timeout=120.0
    )

    # 记录会话ID，后续对话复用
    session_id = agent_client1.session_id

    result = agent_client1.invoke(
        payload={"prompt": "Introduce yourself"},
    )
    print(f"response: {result}\n")
    time.sleep(1)

    # 第二轮对话
    agent_client2 = AgentRuntimeClient(
        agent_name='my-agent-app',
        namespace='default',
        router_url=ROUTER_URL,
        timeout=500,
        connect_timeout=120.0,
        session_id=session_id
    )

    result = agent_client2.invoke(
        payload={"prompt": "What can you do?"},
    )
    print(f"response: {result}\n")
    time.sleep(1)

    # 第三轮对话
    agent_client3 = AgentRuntimeClient(
        agent_name='my-agent-app',
        namespace='default',
        router_url=ROUTER_URL,
        timeout=500,
        connect_timeout=120.0,
        session_id=session_id
    )

    result = agent_client3.invoke(
        payload={"prompt": "Write a Python function for me"},
    )
    print(f"response: {result}\n")


if __name__ == "__main__":
    test_conversation()

上述python脚本首先创建了一个对话，对话的对象是上一步创建的my-agent-appAgent应用，然后连续发起3次对话。输出如下：

2026-06-05 16:33:28,396 | INFO | agentcube.agent_runtime | Bootstrapping AgentRuntime session...
2026-06-05 16:33:29,771 | INFO | agentcube.agent_runtime | AgentRuntime session created: cdb9f642-fcfd-4d96-b024-c49b8fc4baf3
response: {'response': 'Hello Agent received: Introduce yourself', 'agent': 'hello-agent', 'timestamp': '2026-06-05T08:33:29.839193', 'original_prompt': 'Introduce yourself'}

2026-06-05 16:33:30,812 | INFO | agentcube.agent_runtime | Reusing AgentRuntime session: cdb9f642-fcfd-4d96-b024-c49b8fc4baf3
response: {'response': 'Hello Agent received: What can you do?', 'agent': 'hello-agent', 'timestamp': '2026-06-05T08:33:30.912573', 'original_prompt': 'What can you do?'}

2026-06-05 16:33:31,886 | INFO | agentcube.agent_runtime | Reusing AgentRuntime session: cdb9f642-fcfd-4d96-b024-c49b8fc4baf3
response: {'response': 'Hello Agent received: Write a Python function for me', 'agent': 'hello-agent', 'timestamp': '2026-06-05T08:33:31.989551', 'original_prompt': 'Write a Python function for me'}

可以看到3次对话的session_id是相同的，说明 AgentCube 识别到了请求所属中的会话ID，将所有请求都代理到了同一个AgentRuntime实例。

  总 结  

AgentCube 以极速启动、高效调度、原生会话管理、安全隔离四大核心能力，补齐了 K8s 集群承载 AI Agent 工作负载的短板。华为云 CCE 将持续集成 AgentCube ，为用户打造低延迟、高吞吐、强隔离的高性能 AI Agent 运行底座。

相关链接

[1] AgentCube GitHub仓库: https://github.com/volcano-sh/agentcube
[2] Volcano官网: https://volcano.sh
[3] AgentCube设计文档: https://github.com/volcano-sh/agentcube/tree/main/docs/design
[4] Kubernetes 跑 AI Agent，缺的不只是算力——AgentCube 补上了什么: https://bbs.huaweicloud.com/blogs/477468
[5] Python SDK: https://github.com/volcano-sh/agentcube/tree/main/sdk-python
[6] 华为云CCE控制台: https://console.huaweicloud.com/cce2.0/?region=cn-north-9#/cce/cluster/list
[7] AgentSandbox: https://github.com/kubernetes-sigs/agent-sandbox
[8] 华为云分布式缓存服务 DCS: https://support.huaweicloud.com/productdesc-dcs/dcs-pd-200713001.html
[9] Agent示例代码: https://github.com/volcano-sh/agentcube/blob/release-0.1.0/cmd/cli/examples/hello-agent/main.py

关注魔方公众号，获取更多前沿资讯

添加社区小助手k8s2222，进入技术交流群