agentland

README

agentland

agentland 是一个面向 AI Agent 的 Kubernetes 沙箱运行时平台，支持 Sandbox as Tool 和 Agent IN Sandbox 两类场景。通过统一的 Gateway API 暴露能力，提供 Python SDK 和 MCP。

agentland 提供两种主要 Kubernetes 自定义资源定义（CRD），各自对应两类应用场景 CodeInterpreter（通用工具沙箱）和 AgentSession（Agent 运行时沙箱），可通预热池实现沙箱亚秒级启动。

项目同时提供运行在 AgentSession Sandbox 内的轻量 Eino Agent agentd。它直接操作容器工作区，支持本地工具、MCP、Skills、流式事件和文件 Memory，设计与实现见 docs/agentd.md。

app/fe 与 app/be 提供面向用户的 AI 应用生成界面和应用后端，支持项目会话、Run、代码编辑、实时预览与 OCI 镜像发布。发布任务使用远程 BuildKit 构建并推送到指定 Registry，设计与部署见 docs/application-publishing.md。

应用后端默认以 http://{token}.localhost:18081 为每个预览分配独立来源；生产环境使用 PREVIEW_PUBLIC_URL_TEMPLATE=https://{token}.preview.example.com 配合通配 DNS 和 TLS。

架构概览

系统由三个核心组件和一组控制器/CRD 组成。

1. Gateway：接收外部 HTTP 请求
2. AgentCore（controller manager + gRPC）：创建 CR 并等待就绪，将 CR 收敛为 Sandbox 与 Pod 状态
3. Korokd：运行在 CodeInterpreter Sandbox Pod 内，负责代码执行、文件操作、浏览器操作和鉴权功能。

Helm 部署

你可以使用 Helm 直接安装 agentland。当前 chart 路径为 charts/agentland，资源名使用统一前缀策略，执行 helm install agentland ... 时会生成 agentland-* 资源名。

安装或升级 Helm release

helm upgrade --install agentland charts/agentland \
  -n agentland-system \
  --create-namespace

应用生成平台需要一个运行 agentd 的 AgentRuntime。先在沙箱命名空间创建模型密钥，再启用 Chart 中的运行时：

kubectl -n agentland-sandboxes create secret generic agentd-model \
  --from-literal=api-key="$MODEL_API_KEY"

helm upgrade --install agentland charts/agentland \
  -n agentland-system \
  --create-namespace \
  --set agentRuntime.enabled=true \
  --set agentRuntime.model.id="$MODEL_ID" \
  --set agentRuntime.model.apiKeySecret.name=agentd-model

兼容 OpenAI 协议的自托管模型可以同时设置 agentRuntime.model.baseURL，无需鉴权的服务可以省略 apiKeySecret.name。

部署预热池

kubectl apply -f config/samples/agentland_v1alpha1_sandboxpool.yaml

部署验证

安装完成后，你可以用以下命令检查核心资源是否就绪。

kubectl -n agentland-system get pods
kubectl -n agentland-sandboxes get pods

MCP 与 Python SDK

项目提供 Python SDK 和本地 MCP Server。

启动本地 MCP Server

安装 SDK 后，可以直接启动 MCP Server：

--base-url 填入 agentland-gateway 的 URL

pip install agentland
agentland mcp --transport stdio --base-url http://127.0.0.1:8080 --timeout 30

也可以通过环境变量设置默认网关地址与超时：

export AGENTLAND_BASE_URL=http://127.0.0.1:8080
export AGENTLAND_TIMEOUT=30
agentland mcp --transport stdio

Python SDK 快速上手

代码执行示例：

from agentland.sandbox import Sandbox

Sandbox.configure(base_url="http://127.0.0.1:8080", timeout=30)

# 1) 创建代码执行沙箱
sandbox = Sandbox.create()

# 2) 创建执行上下文
context = sandbox.context.create(language="python", cwd="/workspace")

# 3) 第一次执行：定义变量 x
first = context.exec("x = 41")
print(first.stdout)

# 4) 第二次执行：直接访问上一次 exec 定义的变量 x
second = context.exec("print('x + 1 =', x + 1)")
print(second.stdout)

# 5) 删除 context
context.delete()

文件操作示例：

from agentland.sandbox import Sandbox

Sandbox.configure(base_url="http://127.0.0.1:8080", timeout=30)

# 1) 创建代码执行沙箱
sandbox = Sandbox.create()

# 2) 在 sandbox 内写入文件
sandbox.fs.write("/workspace/data.txt", "line1\nline2")

# 3) 读取该文件内容
file_resp = sandbox.fs.read("/workspace/data.txt", encoding="utf8")

# 4) 打印读取结果
print(file_resp.get("content", ""))

浏览器操作示例：

浏览器操作使用 agent-browser 实现

from agentland.sandbox import Sandbox

Sandbox.configure(base_url="http://127.0.0.1:8080", timeout=30)

# 1) 创建代码执行沙箱
sandbox = Sandbox.create()

# 2) 创建 bash context
bash_context = sandbox.context.create(language="bash", cwd="/workspace")

# 3) 在同一个 context 内执行 agent-browser 帮助命令
help_resp = bash_context.exec("agent-browser --help")
print(help_resp.stdout)

# 4) 删除 bash context
bash_context.delete()

核心 CRD

控制面 API Group 为 agentland.fl0rencess720.app/v1alpha1。

• CodeInterpreter：代码执行会话资源
• AgentRuntime：可复用的 Agent 运行时模板，Agent 应用的镜像在此定义
• AgentSession：通用 Agent 会话资源，引用 AgentRuntime
• Sandbox：与实际运行 Pod 一一对应
• SandboxPool：预热 Pod 池
• SandboxClaim：从预热池中分配沙箱的请求

卸载

如果你需要回收 Helm 部署资源，先卸载 release，再按需删除命名空间。

helm uninstall agentland -n agentland-system
kubectl delete ns agentland-sandboxes --ignore-not-found=true

📄 License

agentland 采用 Apache License 2.0 开源许可证发布