这也是 AgentCube 试图解决的问题：在 Kubernetes 的算力底座之上，补齐面向 Agent 工作负载的关键机制缺口，提供一层真正理解会话、沙箱和工具调用语义的 Serverless 编排层。

图 1：AgentCube 整体架构 —— Router 接收请求并路由至沙箱，Workload Manager 管理沙箱生命周期，PicoD 负责沙箱内执行

核心组件一览：

+----------+                  +----------+                  +------------------+
|  Client  | --- 1) HTTP ---> |  Router  | --- 2) alloc --> | Workload Manager |
+----------+                  +----+-----+                  +--------+---------+
                                   |                                 |
                          4) sign JWT                       3) create/claim
                             + proxy                          Sandbox Pod
                                   |                                 |
                                   v                                 v
                              +--------+                    +-------------+
                              | PicoD  | <-- running in --- | Sandbox Pod |
                              +---+----+                    +-------------+
                                  |
                         5) verify JWT
                            execute cmd
                            return result
                                  |
                                  v
                         stdout / stderr / exit_code

// 从请求头提取 Session ID
sessionID := c.GetHeader("x-agentcube-session-id")

// 通过 SessionManager 查找或创建沙箱
sandbox, err := s.sessionManager.GetSandboxBySession(
    c.Request.Context(), sessionID, namespace, name, kind)

// 更新会话最后活跃时间（用于 GC 判定）
s.storeClient.UpdateSessionLastActivity(ctx, sandbox.SessionID, time.Now())

// 反向代理转发至沙箱
s.forwardToSandbox(c, sandbox, path)

POST /v1/namespaces/{namespace}/agent-runtimes/{name}/invocations/*path
GET  /v1/namespaces/{namespace}/agent-runtimes/{name}/invocations/*path
POST /v1/namespaces/{namespace}/code-interpreters/{name}/invocations/*path
GET  /v1/namespaces/{namespace}/code-interpreters/{name}/invocations/*path

apiVersion: runtime.agentcube.volcano.sh/v1alpha1
kind: AgentRuntime
metadata:
  name: my-agent
spec:
  podTemplate:
    containers:
      - name: agent
        image: my-agent:latest
        ports:
          - containerPort: 8080
  targetPort:
    - pathPrefix: "/"
      port: 8080
      protocol: HTTP
  sessionTimeout: 15m
  maxSessionDuration: 8h

apiVersion: runtime.agentcube.volcano.sh/v1alpha1
kind: CodeInterpreter
metadata:
  name: my-interpreter
spec:
  template:
    image: ghcr.io/volcano-sh/picod:latest
    runtimeClassName: kata
    resources:
      requests: { cpu: "500m", memory: "512Mi" }
      limits:   { cpu: "2",    memory: "2Gi"   }
  warmPoolSize: 3
  authMode: picod
  sessionTimeout: 15m
  maxSessionDuration: 8h

+-----------------------------------------------------------+
|                      Warm Pool                            |
|                                                           |
|   +-----------+   +-----------+   +-----------+           |
|   |  Sandbox  |   |  Sandbox  |   |  Sandbox  |  <- idle  |
|   |  (idle)   |   |  (idle)   |   |  (idle)   |           |
|   +-----+-----+   +-----------+   +-----------+           |
|         |                                                 |
|         v  new session --> SandboxClaim                   |
|   +-----------+                                           |
|   |  Sandbox  |  <- claimed, ready to use                 |
|   |  (active) |                                           |
|   +-----------+                                           |
|                                                           |
|   pool replenishes asynchronously                         |
+-----------------------------------------------------------+

ctx, cancel := context.WithTimeout(ctx, timeout)
defer cancel()

cmd := exec.CommandContext(ctx, command[0], command[1:]...)
cmd.Dir = workspaceDir
cmd.Env = mergedEnv

if ctx.Err() == context.DeadlineExceeded {
    exitCode = 124
}

+--------------+                     +-------------------------+
|    Router    |                     |    Kubernetes Secret    |
|              |  generate on boot   |  picod-router-identity  |
|  RSA-2048    | ------------------> |                         |
|  key pair    |                     |  private.pem  (Router)  |
|              |                     |  public.pem   (PicoD)   |
+------+-------+                     +------------+------------+
       |                                          |
       | sign with                    Workload Manager injects
       | private key                  PICOD_AUTH_PUBLIC_KEY
       | (5min TTL)                   into sandbox env
       |                                          |
       v                                          v
+--------------+   RS256 JWT Token   +--------------+
| Router signs | ------------------> | PicoD verify |
| (private key)|                     | (public key) |
+--------------+                     +--------------+

session:{sessionID}       -> SandboxInfo JSON
session:expiry            -> Sorted Set (score = 到期时间戳)
session:last_activity     -> Sorted Set (score = 最后活跃时间)

from agentcube import CodeInterpreterClient

interpreter = CodeInterpreterClient()

result = interpreter.run_code("python", "print('Hello, AgentCube!')")
print(result)

interpreter.write_file(content="data", remote_path="/workspace/data.txt")
interpreter.download_file("/workspace/data.txt", "./local_data.txt")

LangChain / LangGraph 集成

AgentCube 可以作为 LangChain 的 @tool 接入 ReAct Agent 工作流，将代码执行部分自然下沉到受隔离的沙箱环境中，应用层无需直接理解底层实例调度和生命周期管理。

Dify 插件

项目仓库中的 dify-plugin 目录提供了 Dify 工具接入方式，使 Dify 用户也可以直接消费 AgentCube 的沙箱能力。

  快速上手  

前置条件

• Kubernetes 集群 v1.24+
• Redis 或 Valkey 实例
• sigs.k8s.io/agent-sandbox v0.1.1 CRD 已安装

Helm 安装

helm install agentcube manifests/charts/base \
  --namespace agentcube-system --create-namespace \
  --set redis.addr=<redis-host>:6379 \
  --set redis.password="<password>"

创建第一个 CodeInterpreter

apiVersion: runtime.agentcube.volcano.sh/v1alpha1
kind: CodeInterpreter
metadata:
  name: my-interpreter
  namespace: default
spec:
  template:
    image: ghcr.io/volcano-sh/picod:latest
    resources:
      requests: { cpu: "500m", memory: "512Mi" }
      limits:   { cpu: "2",    memory: "2Gi"   }
  warmPoolSize: 2
  sessionTimeout: 15m
  maxSessionDuration: 8h

发起调用

curl -X POST \
  http://<router-host>/v1/namespaces/default/code-interpreters/my-interpreter/invocations/api/execute \
  -H "Content-Type: application/json" \
  -d '{"command": ["python3", "-c", "print(1+1)"]}'

响应头中的 x-agentcube-session-id 即为会话 ID。后续请求继续携带它，就可以复用同一个沙箱执行环境。

  致 谢  

从项目启动到今天，AgentCube 已经吸引了多位社区开发者参与共建。感谢所有为 AgentCube 做出贡献的开发者：

相关链接

AgentCube 开源项目欢迎广大开发者参与。无论是提交 Issue、贡献 PR，还是在你的项目中试用 AgentCube，都是对项目的支持。