agent-dx:基于 Rust 的 Agent 分布式执行底座

openJiuwen Agent Runtime 的分布式执行底座

English | 中文

Agent DX（Agent Distributed eXecutor）是 openJiuwen Agent Runtime 的一种分布式执行底座，Agent 层提供 Template 与 AgentBinding 管理，由无状态 Activator 按需启动用户 Harness，支持 HTTP、WebSocket 和 SSH 访问。同时提供公开 Environment API 与 SDK、分布式调度、隔离执行、流量路由、运行时操作、Checkpoint 恢复与部署工具，并保持执行后端可替换。

🚀 快速开始 · 📐 架构 · 📦 Environment SDK · ⚙️ 部署 · 🔐 管理 · ✅ 测试门禁

🎯 何时使用 Agent DX

目标	部署方式	所需条件
为单个 Agent 服务增加隔离命令、文件、终端和端口操作	单机部署	一台 Linux 主机、独立托管的 sandboxd、ADX 发布包和 Environment 网络
让多个 Agent 服务共享跨机器执行资源	按角色多机部署	持久化 Redis、一个 Coordinator 部署、一个或多个 Worker 部署和可访问的 Gateway
以可重复验收方式运行生产形态集群	Kubernetes	Linux Worker、持久化 Redis、组件证书、Worker 上的 sandboxd 和 ADX Kubernetes E2E 配置
暂停、恢复、克隆或接管长时间任务	单机或分布式	支持 Checkpoint 的运行时，以及本地或 S3 兼容 Checkpoint 存储
调度加速卡工作负载	分布式	Worker 上报 GPU/NPU 清单，Environment 规格申请匹配设备

🧩 Agent DX 在技术栈中的位置

层	负责内容	与 Agent DX 的关系
Agent 框架或业务应用	Prompt、工具、会话、任务逻辑和业务策略	调用公开 Environment SDK 或 HTTP API，不进入平台调度或生命周期状态机
Agent DX	认证、放置、Environment 状态、路由、恢复和可观测	在多个节点和执行后端之上提供统一分布式执行契约
sandboxd	运行时创建、隔离、网络和 Checkpoint 原语	作为每个 Worker 上的外部服务，由 adxlet 的运行时驱动调用
Runtime 内的 Execd	命令、文件、终端、端口、活动统计和恢复协作	Ingress 与 Relay 完成归属和 generation 校验后转发数据请求
Redis 与对象存储	权威集群元数据和可选共享 Checkpoint 制品	Redis 保存控制状态与服务发现；对象存储支持跨节点访问 Checkpoint

🔄 工作流程

步骤	发生的事情	所在模块
1 · 接入	调用方认证后，通过统一公开契约创建或操作 Environment。	gateway/apiserver/、platform/sdk/environment/python/
2 · 放置	API Server 使用本地优先准入或提交 Coordinator。Coordinator 在 Shard 间轮转，Shard 负责排队、过滤、评分和节点预留。	platform/coordinator/、platform/crates/scheduling/
3 · 运行	adxlet 完成本机最终准入、串行管理 Environment 生命周期，并调用 sandboxd 创建带 Execd 的 Runtime。	platform/adxlet/、third_party/sandboxd/、platform/runtime/execd/
4 · 操作与恢复	Ingress 把数据请求路由到归属 Relay。版本化归属隔离旧 Runtime；暂停、恢复、快照、重启策略和对账在故障后收敛状态。	gateway/、platform/adxlet/、Redis、Checkpoint 存储

API Server 默认内嵌 Ingress，adxlet 默认内嵌 Relay；显式拆分进程时仍复用同一套契约。

📦 安装

ADX 发布包面向 Linux，提供 adx-coordinator、默认内嵌 Relay 的 adxlet、默认内嵌 Ingress 的 adx-apiserver、供显式分进程部署的 adx-ingress 与 adx-relay、adxctl、Execd、Python Environment SDK 和托管 Redis 二进制。调试转发程序不随包发布。sandboxd 由部署环境独立托管，版本固定在 third_party/sandboxd/source.json。

mkdir adx-release
tar -xzf adx-release.tar.gz -C adx-release
sudo ./adx-release/install.sh

安装器校验清单、文件摘要和主机架构，将版本写入 /opt/adx/releases/<commit> 并原子切换 /opt/adx/current。升级会保留 /opt/adx/config、/opt/adx/data 和 /opt/adx/run，同时通过 /usr/local/bin 提供 adxctl 命令。

🔧 快速开始

默认 standalone profile 在一台主机启动托管 Redis、Coordinator、内嵌 Relay 的 adxlet，以及内嵌 Ingress 的 API Server。开始前先准备 sandboxd、网络、证书和初始管理员密钥。

sudo adxctl config init --profile standalone
sudoedit /opt/adx/config/deployment.yaml
sudo adxctl validate
sudo adxctl run

在管理员工作站安装平台无关的 wheel，然后通过公开 HTTPS API 创建首个租户 Key：

pipx install ./adxadmin-0.1.0rc2-py3-none-any.whl
export ADX_ENDPOINT=https://adx.example.com:8443
export ADX_CA_FILE=$HOME/.config/adx/public-ca.pem
export ADX_ADMIN_TOKEN_FILE=$HOME/.config/adx/admin.key
adxadmin key create --tenant example

查询、分页、吊销、JSON 输出和错误语义见 adxadmin 指南。

在另一终端安装发布包中的 SDK，并连接公开 Gateway：

python3 -m venv /opt/adx-client
/opt/adx-client/bin/python -m pip install /opt/adx/current/sdk/adx_environment-*.whl

export ADX_SERVER_ADDRESS=adx.example.com:8443
export ADX_GATEWAY_ADDRESS=adx.example.com:8443
export ADX_TOKEN="$(cat /secure/path/tenant-api-key)"
export ADX_TLS=1
export ADX_GATEWAY_TLS=1
export ADX_ENVIRONMENT_IMAGE=python:3.12-slim

创建 Environment，通过 Execd 执行命令，然后显式删除：

import os
from adx_environment import Environment

environment = Environment(
    image=os.environ["ADX_ENVIRONMENT_IMAGE"],
    cpu=1000,
    memory=2048,
    name="readme-demo",
)
try:
    result = environment.commands.run("printf 'hello from ADX\\n'")
    print(result.stdout)
finally:
    environment.kill()

镜像必须由当前 sandboxd 和 ADX Runtime Environment 支持。暂停恢复、可复用快照、放置约束、挂载、网络、数据面安全和重试语义见 Environment SDK 指南。

🏗️ 部署组合

拓扑	adxctl profile	本机进程
单机托管 Redis	standalone	Redis、Coordinator、adxlet + Relay、API Server + Ingress
单机外置 Redis	standalone-external-redis	Coordinator、adxlet + Relay、API Server + Ingress
控制节点	coordinator	Coordinator；Redis 可独立部署，也可加入完整 YAML
Worker 节点	node	默认 adxlet + Relay
接入节点	ingress-api	默认 API Server + Ingress

每台主机使用独立的 /opt/adx/config/deployment.yaml。集群成员共享 Redis URL、namespace 和 mTLS 信任；每个 Worker 使用唯一 node_id 和可访问的控制、代理地址。启动顺序为 Redis → Coordinator → Worker → API Server。仅在确实需要分进程时设置 proxy_mode: standalone 或 ingress_mode: standalone。

YAML 字符串支持 ${VAR} 与 ${VAR:-default}。使用 adxctl config dump 查看合并后的 profile 和主机覆盖。完整字段与证书说明见 adxctl 参考、单机部署指南和配置示例。

📐 核心抽象

ADX 将稳定逻辑身份与可替换物理执行分开：

抽象	含义与边界
Agent AgentBinding	保存业务绑定及其到稳定逻辑 Environment 的映射，由无状态 Activator 管理
Environment	面向应用的公开 API 与 SDK 句柄
Platform Environment	稳定内部身份，包含租户、规格、生命周期和期望／实际状态
RuntimeProfile	部署侧 rootfs、bootstrap 与启动环境变量配置；不是运行中的 Environment
Runtime	Environment 在一个节点上的一次 sandboxd 执行；重启或恢复可替换 Runtime
Assignment	带 generation 的权威节点和设备归属，用于隔离迟到的旧执行
Route / Binding	发布到 Ingress 的版本化归属，以及 Relay 转发前的本机复核
Restore Point / Snapshot	恢复点保留 Environment ID；可复用 Snapshot 创建新的 Environment
Request ID / Operation ID	用于重试、去重、结果查询和对账的一次逻辑写身份

固定控制链路为 Agent／应用 → Environment SDK／HTTP API → API Server → Coordinator／Shard 调度器或本地优先 adxlet → sandboxd。运行时数据请求走 Ingress → Relay → Execd，不进入生命周期队列。公开生命周期与错误响应使用 environmentId；目录查询保留 /api/instances 及其 instance_id 查询参数。内部 Rust 类型、RPC、持久化字段、指标和运行身份统一使用 Environment 命名。

Execd 支持主动向 adxlet 建立独立双向控制流，上报 Ready 和 checkpoint 状态，接收准备与完成命令。通过节点运行时控制配置启用，需要同时更新节点程序和运行镜像内的 Execd；未配置时运行时协作使用 HTTP。接口契约与组件验证说明执行身份隔离、重连及权威结果提交后的应答规则。

local-only checkpoint 成功表示所属节点的制品可读且恢复点元数据已提交；adxlet 不强制刷盘，不保证突然断电或宿主机崩溃后的制品完整性。对象存储仍要求上传完成后才返回成功。详见Checkpoint 存储契约。

组件命名与抽象。

✨ 能力

• Environment 创建、查询、删除、暂停、恢复、可复用快照和基于快照的克隆。
• 中心调度与本地优先创建，支持 CPU、内存、磁盘、GPU/NPU 设备、标签、亲和约束和偏好评分。
• API Key 管理员／租户身份和可配置内部 mTLS。
• 版本化路由发布与同步本机绑定检查。
• 节点对账、重启策略、空闲删除、Checkpoint 恢复、本地／S3 兼容存储和引用感知制品清理。
• Prometheus Metrics、OpenTelemetry Trace、结构化日志、滚动、gzip 压缩和外部 Collector 对接。
• 托管或外置 Redis 的进程部署，以及 Kubernetes 端到端部署配置。

🛠️ 开发与测试

根 Cargo workspace 包含平台和 Agent 组件；Python 包独立构建。构建产物放在 out/ 或显式配置的外部缓存。

make help
make rust-check
make rust-test
make agent-test
PYTHONPATH=platform/sdk/environment/python \
  python -m pytest -q -c platform/sdk/environment/pytest.ini \
  platform/sdk/environment/python/tests
make package PYTHON=/path/to/venv/bin/python

Agent FS（AFS）由 OwnerFs 与 DistributedFs（DFS）组成，是 ADX 的可选文件系统子系统。默认构建、测试和发布包不包含它的运行二进制，也不引入它的系统依赖。共享 source gate 只在显式设置 ADX_WITH_AFS=1 时纳入 AFS 检查，并且不会把 AFS artifact 注入默认发布包。本地运行文件系统 gate 或构建显式带文件系统的包时设置 ADX_WITH_AFS=1：

ADX_WITH_AFS=1 make afs-check
ADX_WITH_AFS=1 make platform-release
python3 build/ci/run.py afs

afs-check 使用默认 OwnerFs 和 DFS feature。可选 all-features/RDMA lint 必须显式执行（ADX_AFS_ALL_FEATURES=1 make afs-lint），并先检查 libibverbs 开发文件。

子系统职责、当前范围和真实限制见 架构边界、部署说明、测试验收和 AFS 演进计划。来源与带日期的历史证据保留在 docs/migration/；它们不定义当前运行合同。发布包配置示例位于 AFS 示例目录。

组件与集成测试使用 python3 build/ci/run.py <suite>。端到端门禁使用已安装发布包、公开 Environment SDK、Redis、Gateway、控制面、sandboxd 和 Execd。环境要求与门禁定义见控制面 CI和 Kubernetes E2E 指南。

Buildkite 使用相互独立的 agent-dx、agent-dx-python-sdk、agent-dx-admin 和 agent-dx-full-test 四条流水线。SDK 和 admin 流水线始终构建并检查 wheel/sdist； 各自的 PyPI 上传需要独立显式开关与仓库 release tag。Full 流水线只消费显式指定的 基础包与 SDK build UUID，不重新构建任一候选；契约见 Buildkite 流水线说明。

SDK 发布名为 adx-environment，Python 导入名为 adx_environment，CLI 为 adx-environment。ADX 环境变量使用 ADX_ 前缀，内部品牌 HTTP 头使用 X-ADX-。

📚 深入了解

• 架构与仓库目录
• Agent 使用
• Environment API与 OpenAPI
• 数据面 OpenAPI
• 运行时 HTTP 操作与错误
• Environment Python SDK
• 部署配置与配置示例
• 远程集群管理与 API Key 管理
• 调度、节点生命周期与路由发布
• Checkpoint 与快照存储
• Metrics、日志与分布式 Trace
• Rust 编程规范
• 发布流水线与软件包布局
• 品牌与架构资源

许可证

Agent DX 使用 Apache License 2.0。