agent-dx (Agent Distributed eXecutor) 是 openJiuwen Agent Runtime 的一种分布式执行底座，用于承载 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。