AgentCube是什么？在华为云CCE上部署AI Agent完整指南

作为 Volcano 社区的子项目，AgentCube 面向 AI Agent 工作负载提供专用控制面与数据面，帮助开发者在 Kubernetes 集群中更高效地运行 Agent 应用。本文将结合华为云 CCE（云容器引擎）环境，介绍 AgentCube 的安装、配置以及 CodeInterpreter、AgentRuntime 的基础使用方式。

AgentCube 适合解决哪些问题？

AgentCube 面向 AI Agent 交互式工作负载，重点解决启动速度、调度效率、会话管理和安全隔离问题。

1. 极速启动

AgentCube 通过 Warm Pool（预热池）机制，提前创建并暂停一批沙箱实例。当 Agent 请求到来时，可采用 “Claim-and-Go” 方式快速分配可用沙箱，减少冷启动等待时间。

对于需要频繁启动代码解释器、工具调用环境或临时执行上下文的 Agent 应用来说，预热池可以明显改善首请求体验。

2. 高效调度

AgentCube 借助 Volcano Agent Scheduler 的乐观并发控制与精简调度策略，提升 Agent 工作负载的调度吞吐能力。

同时，它可以与 Volcano 原有 Batch Scheduler 协同工作，使 Agent 任务与传统批处理作业在同一集群内实现统一调度和资源协调。

3. 原生会话管理

AgentCube 以 Session ID 作为核心路由标识。会话请求到来时，系统能够自动识别并路由到对应沙箱；当沙箱休眠后，也可以按需唤醒。

这使多轮对话、连续代码执行、上下文保持等场景更加自然，避免每次请求都重新创建运行时环境。

4. 安全隔离

AgentCube 为每个会话分配独立沙箱，确保计算、内存和文件系统的隔离，降低跨租户数据泄露风险。

同时，AgentCube 支持以安全容器方式运行 Agent。结合安全运行时，可进一步实现内核级隔离，适合执行 LLM 生成代码、插件调用等风险更高的场景。

环境准备

在华为云 CCE 上使用 AgentCube 前，需要完成以下准备：

已创建 1.29 或更高版本的 CCE 集群；
本地 Python 版本不低于 3.11；
安装 AgentCube SDK：

pip install agentcube_sdk

此外，由于 AgentCube 运行时依赖 Redis 维护会话状态和索引，建议使用华为云分布式缓存服务 DCS，以获得更好的稳定性和可扩展性。

安装 AgentCube 插件

华为云官网：点击直达

AgentCube 目前已上架华为云 CCE 插件市场。用户可以登录华为云 CCE 控制台，进入目标集群的插件中心，找到 AgentCube 插件并进行安装配置。

AgentCube 主要包含以下组件：

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

安装插件时，需要重点配置以下参数：

参数	说明
`redis.addr`	Redis 地址，必须配置
`redis.password`	Redis 密码，必须配置
`agentSandbox.install`	是否自动安装 agent-sandbox
`agentSandbox.extensions`	是否启用 agent-sandbox extension controller
`volcano.scheduler.enabled`	是否安装 volcano agent-scheduler 调度器

其中，AgentCube 插件运行依赖 agent-sandbox。如果配置 agentSandbox.install=true，插件会自动安装；如果集群中已手动安装 agent-sandbox，可将其设置为 false 跳过安装。

如果需要从集群外访问 AgentCube，可为 workloadmanager 和 agentcube-router 的 Service 绑定 ELB Ingress。

开始使用 AgentCube

步骤一：设置环境变量

首先配置 workloadmanager 和 agentcube-router 的访问地址：

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

其中：

workloadmanager-addr 和 workloadmanager-port 为 workloadmanager 的访问地址和端口；
agentcube-router-addr 和 agentcube-router-port 为 agentcube-router 的访问地址和端口。

使用 CodeInterpreter

CodeInterpreter 是 AgentCube 的两大核心能力之一，另一项是 AgentRuntime。

CodeInterpreter 是专为执行 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
    resources:
      requests:
        cpu: "100m"
        memory: "128Mi"
      limits:
        cpu: "500m"
        memory: "512Mi"
  sessionTimeout: "15m"
  maxSessionDuration: "8h"
  warmPoolSize: 5

其中：

sessionTimeout: "15m" 表示空闲 15 分钟后超时；
maxSessionDuration: "8h" 表示最大会话时长为 8 小时；
warmPoolSize: 5 表示预热 5 个 Pod；
示例镜像当前支持执行 Shell 和 Python 代码。

执行部署：

kubectl apply -f code-interpreter.yaml

验证是否部署成功：

kubectl get codeinterpreter

等待一段时间后，执行以下命令：

kubectl get pods | grep my-codeinterpreter

如果可以看到已经预热出的 5 个 CodeInterpreter Pod，说明预热池已经生效。

远程执行第一段代码

创建 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)

该脚本会连接到已部署的 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 的会话保持能力。

创建 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():
    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")

    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")

    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 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

可以看到，三轮请求使用的是同一个 session_id。这说明 AgentCube 识别到了请求所属会话，并将所有请求代理到同一个 CodeInterpreter 实例，而不是重新创建新的沙箱。

同时，第 2、3 轮请求能够读取第 1 轮请求上传的文件，说明该 CodeInterpreter 实例没有被销毁和重建，其运行时状态，包括文件系统、内存变量和进程上下文，都在请求之间得到保留。这正是 CodeInterpreter 区别于无状态函数调用的重要能力。

使用 AgentRuntime

与 CodeInterpreter 不同，AgentRuntime 支持完整的 PodSpec 自定义，更适合对话、工具调用等常规 Agent 场景。

部署 AgentRuntime

首先创建 agent.py 和 requirements.txt 文件。其中，agent.py 可使用官方提供的 Agent 示例代码，requirements.txt 内容如下：

agentcube_sdk

使用以下 Dockerfile 制作 Agent 容器镜像，并将镜像上传至华为云 SWR：

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .

RUN pip install --no-cache-dir -r requirements.txt

COPY agent.py /app/

EXPOSE 8080

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}}
          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"
  maxSessionDuration: "8h"
status: {}

其中：

{{agent image}} 需要替换为已构建并上传至华为云 SWR 的 Agent 容器镜像；
sessionTimeout 表示空闲会话超时时间；
maxSessionDuration 表示最大会话持续时间；
如启用 volcano agent-scheduler，可将 schedulerName 配置为 agent-scheduler。

执行部署：

kubectl apply -f agent-runtime.yaml

验证部署状态：

kubectl get agentruntime

示例输出：

NAME           AGE
my-agent-app   1m

这说明名为 my-agent-app 的 AgentRuntime 已部署成功。

与 Agent 进行对话

创建 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
    )

    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()

该脚本会创建一个对话对象，目标是上一步部署的 my-agent-app，并连续发起 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'}

可以看到，三次对话的 session_id 相同，说明 AgentCube 识别到了请求所属会话，并将所有请求持续代理到同一个 AgentRuntime 实例。

这对多轮对话、上下文保持、工具调用链路非常重要。Agent 不需要在每次请求时重新初始化运行环境，用户也能获得更连续的交互体验。