ANet4D Python SDK quickstart
In about 15 minutes you install the anet4d SDK, write an example agent, run a 60 s L1 episode with 3 drones on the high-fidelity physics tier (physics = realistic, Gazebo Sim lockstep), confirm that the action streams are byte-identical whether the agent connects over the wire protocol or runs inside the Env process, and finally repeat the episode on the fast simulation tier (physics = fast) without code changes. Every output shown below comes from a real run; section 0 lists the measurement conditions.
The SDK was named drone4d up to V0.3.1. In V0.3.2, drone4d remains a deprecated compatibility alias that re-exports anet4d and emits a DeprecationWarning, and the command drone4d-agent still works with a notice on standard error; both will be removed in the next release. Replace drone4d with anet4d in imports and commands. The wire protocol drone4d.bench.wire.v1, the socket path /run/drone4d/agent.sock and the variable DRONE4D_AGENT_SOCK are legacy identifiers and keep their names.
0. Measured runs
Steps |
Environment |
Measured |
|---|---|---|
Steps 2 to 4 (install, write, run) |
dmax, a fresh |
From container start to the end of the 3-drone 60 s high-fidelity episode: 49.4 s wall clock, of which the Env episode took 38.6 s |
Section 4.3 (in-process run) |
dmax, d3-gz image (Python 3.12, |
The same episode took 36.7 s wall clock; the per-drone action stream sha256 equals section 4.2 |
Section 5 (fast simulation tier) |
The researcher-side container from section 4.2; the platform side runs FleetSim |
From container start to the end of the 3-drone 60 s fast simulation episode: 47.6 s wall clock, of which the Env episode took 39.2 s |
Clean-host drill (ADR-202) |
dmax, a fresh |
45.0 to 51.2 s from container start (limit 900 s); recorded in |
Measured on 2026-10-18 (UTC), with the package under its former name drone4d; the package name and version in the installation output are shown for the renamed package anet4d 0.3.2, whose modules are unchanged apart from the name. The --help output in section 2 and the build in section 8 were rerun with anet4d 0.3.2 on 2026-10-25 (UTC). The platform side (section 4.1) was started first and waited for the agents. The formal clean-host drill runs in a fresh python:3.12-slim container on dmax under ADR-202 and is recorded in docs/impl/D3-SDK-上手演练记录.md.
1. Prerequisites
Researcher host: Linux x86_64 with Python 3.11, 3.12 or 3.13. The agent depends only on
anet4dand its dependencies; no repository code is needed.Platform side (runs the Env): the repository environment (
PYTHONPATHwithpythonandtools/sdk/anet4d/src), the world packageoryahovo-crop1and the compiled eventcrop-handoff-001; the high-fidelity tier also needs the d3-gz image (Gazebo Sim with the native Gazebo plugins of this repository). Internal workspace members can use the world package and event already in place under/data/anet-drone4d-d3/d3devon dmax.The agent and the Env exchange frames over a local Unix socket (wire protocol
drone4d.bench.wire.v1): both run on the same host, or the agent runs in a container on that host with the socket directory bind-mounted.
2. Install the SDK
anet4d is not published on PyPI. The wheel ships as a release attachment, or you can build it from source as described in section 8. Put the wheel and its dependencies in one directory and install:
python3 -m venv ~/d4d
. ~/d4d/bin/activate
pip install --no-index --find-links /wheels "anet4d[l2]"
Successfully installed anyio-4.15.1 certifi-2026.7.22 anet4d-0.3.2 h11-0.16.0 httpcore-1.0.9 httpx-0.28.1 idna-3.20 msgpack-1.2.2 numpy-2.4.6 pillow-11.3.0 typing_extensions-4.16.0
The core dependencies are msgpack (wire protocol) and httpx (bench API client). The l2 extra adds numpy and pillow for the reference detector ref_det_v1 under L2 observations; install anet4d without extras if you only run L1. When the host can reach a package index, drop --no-index to fetch the dependencies online.
Check the container entry point:
anet4d-agent --help
usage: python -m anet4d.serve [-h] [--baseline BASELINE] [--sock SOCK]
[factory]
positional arguments:
factory pkg.module:Factory
options:
-h, --help show this help message and exit
--baseline BASELINE built-in baseline policy name
--sock SOCK default $DRONE4D_AGENT_SOCK or /run/drone4d/agent.sock
anet4d-agent is equivalent to python -m anet4d.serve.
3. Write an agent
An agent subclasses anet4d.agent.DroneAgent, with one instance per drone, and implements two methods:
reset(config)is called once at the start of an episode;configis abench/agent_config.v1document (task brief, vehicle limits, sensors, decision latency and communication parameters).step(obs, inbox)is called at every control step (10 Hz);obsis abench/obs.v1observation,inboxholds the inter-drone messages received in this step, and the method returns abench/act.v1action.
Observations and actions are plain dicts; anet4d.agent provides action builders such as act, nav_takeoff, nav_goto, gimbal_look_at, out_msg and report. Save the following file as plaza_watch.py in your working directory (it is identical to docs/sdk/examples/plaza_watch.py in the repository):
"""快速上手示例 Agent `PlazaWatch`(docs/sdk/quickstart.zh-CN.md、quickstart.en.md)。
每架机起飞到各自的高度层,飞往分配给本机的公开锚点斜上方站位,云台持续对准锚点,并每 10 s 向标准错误输出累计检测数。
L1 直接读取观测中的检测列表;L2 由参考检测器 `ref_det_v1`(`anet4d.perception.ref_det.L2Perception`,需要 extras `l2`)
从相机图像得到同形的检测。示例不发送机间消息、不提交 report;report 与协同的写法见基线策略 `anet4d.baselines`。
同一份代码不改动地运行于各物理档(`physics = realistic`、`fast`)与观测档(L1、L2);策略内无随机数、无墙钟依赖,
同一种子两次运行的动作流逐字节一致。
"""
from __future__ import annotations
import sys
from anet4d.agent import DroneAgent, act, gimbal_look_at, nav_goto, nav_takeoff
STANDOFF_M = 30.0 # 站位相对锚点向西、向南各偏移 30 m(斜视)
LAYER_M = 8.0 # 机间高度分层间隔:同高度交叉航线会机间碰撞
CRUISE_MPS = 6.0
LOG_EVERY = 100 # 每 100 步(10 s)输出一次累计检测数
class PlazaWatch(DroneAgent):
def reset(self, config: dict) -> None:
super().reset(config)
self.uav = config["uav_id"]
brief = config["brief"]
fleet = sorted([self.uav, *config["peers"]])
i = fleet.index(self.uav)
lo, hi = brief["area"]["alt_agl_range_m"]
self.alt = min(max(0.5 * (lo + hi) + LAYER_M * (i - 0.5 * (len(fleet) - 1)), lo + 2.0), hi - 2.0)
anchor = brief["anchors"][i % len(brief["anchors"])]["pos_enu_m"]
self.anchor = (float(anchor[0]), float(anchor[1]))
self.station = (self.anchor[0] - STANDOFF_M, self.anchor[1] - STANDOFF_M)
self.cam = next(s["sensor_id"] for s in config["sensors"] if s["kind"] == "camera")
self.perception = None
if config["obs_level"] != "L1":
from anet4d.perception.ref_det import L2Perception
self.perception = L2Perception(config)
self.ground: float | None = None
self.in_mission = config["start"]["state"] == "airborne" # 空中出生时不起飞,直接飞往站位
self.seen = {"person": 0, "vehicle": 0}
def step(self, obs: dict, inbox: list[dict]) -> dict:
k = obs["k"]
if self.ground is None:
self.ground = float(obs["ground_hint"]["dtm_m"])
dets = self.perception.detect(obs) if self.perception is not None else obs["sensors"].get("detections", [])
for d in dets:
self.seen[d["class"]] = self.seen.get(d["class"], 0) + 1
if k % LOG_EVERY == 0 and k > 0:
print(f"{self.uav} k={k} detections person={self.seen['person']} vehicle={self.seen['vehicle']}", file=sys.stderr, flush=True)
if not self.in_mission:
if k == 0:
return act(k, nav=nav_takeoff(self.alt))
climbed = obs["nav"]["pos_enu_m"][2] - self.ground >= self.alt - 3.0
if obs["status"]["mode"] != "airborne" or not climbed:
return act(k) # 爬升期间不下发新指令,沿用起飞指令
self.in_mission = True
z = self.ground + self.alt
return act(k, nav=nav_goto((*self.station, z), CRUISE_MPS), gimbal=gimbal_look_at(self.cam, (*self.anchor, self.ground)))
Notes: navigation commands use the navigation solution delivered by the Env (a noisy estimate), never ground truth; a step without a new command keeps the previous one; the Env-side action guard validates every action against the schema and the vehicle limits and writes the receipts to agents/<uav>/acts.jsonl in the run directory.
4. Run the example agent
4.1 Platform side: start the environment and wait for agents
Run from the repository root (inside the d3-gz image for the high-fidelity tier). run_quickstart.py builds a local development Env (not ranked) with anet4d.bench.make(..., physics="realistic") and listens on one socket per drone:
PYTHONPATH=python:tools/sdk/anet4d/src python docs/sdk/examples/run_quickstart.py \
--spec configs/bench.d3/crop-handoff-001.l1-3uav.run_spec.json \
--worlds-root worlds --events-root d3data/events --physics realistic --gz-launcher local \
--gz-export-root var/gz-export --duration-s 60 --seed 1 --out runs/quickstart-1 --sock-root /tmp/d4d-sock
uav-01: waiting for an agent on /tmp/d4d-sock/uav-01/agent.sock
uav-02: waiting for an agent on /tmp/d4d-sock/uav-02/agent.sock
uav-03: waiting for an agent on /tmp/d4d-sock/uav-03/agent.sock
The default wait is 300 s (--hello-timeout-s). With --gz-launcher docker, Gazebo Sim runs as a sibling d3-gz container and the host does not need Gazebo Sim installed.
4.2 Researcher side: connect the agents
In the environment from step 2, in the directory that holds plaza_watch.py, start one process per drone:
for u in uav-01 uav-02 uav-03; do
python -m anet4d.serve plaza_watch:PlazaWatch --sock /tmp/d4d-sock/$u/agent.sock 2> $u.log &
done
wait
uav-01.log:
uav-01 k=100 detections person=119 vehicle=0
uav-01 k=200 detections person=701 vehicle=0
uav-01 k=300 detections person=1398 vehicle=0
uav-01 k=400 detections person=2082 vehicle=0
uav-01 k=500 detections person=2886 vehicle=0
When the episode ends, the Env sends CLOSE and the agent processes exit with status 0; the platform side prints a one-line summary on standard output:
{"acts_sha256": {"uav-01": "dccb13582cb385756127c40e8eddc8fba6297bd8311dc8ee910ff91380e1f703", "uav-02": "8bfa3f7133cbbb89be1d7217feacceb6284bf25587407be6014862e0fd191fa4", "uav-03": "687b45b8bb0821efcd455e6dac0f405c7638e3d4d92a0c8526f475cb01c2f112"}, "duration_s": 60.0, "event": "crop-handoff-001", "n_ticks": 600, "obs_level": "L1", "physics": "realistic", "reports": 0, "run_id": "quickstart-1", "schema": "drone4d.quickstart.summary.v1", "tier": "realistic", "timeouts": {"uav-01": 0, "uav-02": 0, "uav-03": 0}, "wall_s": 38.63, "wire": {"uav-01": {"exited": null, "protocol_errors": 0}, "uav-02": {"exited": null, "protocol_errors": 0}, "uav-03": {"exited": null, "protocol_errors": 0}}, "world": "oryahovo-crop1"}
Field |
Meaning |
|---|---|
|
Number of control steps (10 Hz × 60 s) |
|
Per-drone steps that exceeded the per-step wall-clock budget; a timed-out step keeps the previous command |
|
Per-drone wire protocol errors and abnormal exits ( |
|
sha256 of each drone's action stream |
|
Number of accepted reports (the example submits none) |
The run directory runs/quickstart-1/ holds the run manifest manifest.json, the actions and receipts in agents/<uav>/acts.jsonl, the recording raw.mcap and the physics tier records in phys/.
4.3 In-process run
For development and debugging you can run the same episode with an in-process agent in the repository environment, without sockets:
PYTHONPATH=python:tools/sdk/anet4d/src:docs/sdk/examples python docs/sdk/examples/run_quickstart.py \
--spec configs/bench.d3/crop-handoff-001.l1-3uav.run_spec.json \
--worlds-root worlds --events-root d3data/events --physics realistic --gz-launcher local \
--gz-export-root var/gz-export --duration-s 60 --seed 1 --out runs/quickstart-1-inproc --agent plaza_watch:PlazaWatch
{"acts_sha256": {"uav-01": "dccb13582cb385756127c40e8eddc8fba6297bd8311dc8ee910ff91380e1f703", "uav-02": "8bfa3f7133cbbb89be1d7217feacceb6284bf25587407be6014862e0fd191fa4", "uav-03": "687b45b8bb0821efcd455e6dac0f405c7638e3d4d92a0c8526f475cb01c2f112"}, "duration_s": 60.0, "event": "crop-handoff-001", "n_ticks": 600, "obs_level": "L1", "physics": "realistic", "reports": 0, "run_id": "quickstart-1", "schema": "drone4d.quickstart.summary.v1", "tier": "realistic", "timeouts": {"uav-01": 0, "uav-02": 0, "uav-03": 0}, "wall_s": 36.7, "world": "oryahovo-crop1"}
The acts_sha256 values of all three drones equal those of section 4.2: the action streams are byte-identical whether the agent runs in a separate environment over the wire protocol (a Python 3.11 container in section 0) or inside the Env process. The equivalent Python code:
import json
from anet4d.bench import make
from anet4d.runner import run_episode
from plaza_watch import PlazaWatch
with open("configs/bench.d3/crop-handoff-001.l1-3uav.run_spec.json", encoding="utf-8") as f:
run_spec = json.load(f)
run_spec.update(ranked=False, duration_s=60)
env = make(run_spec, run_id="dev-1", seed=1, worlds_root="worlds", events_root="d3data/events", out_dir="runs/dev-1",
physics="realistic", gz={"launcher": "local", "export_root": "var/gz-export"})
manifest = run_episode(env, lambda uav: PlazaWatch())
print(manifest["n_ticks"], manifest["pose_sha256"])
5. Switch the physics tier and the observation level
The agent code stays unchanged; only the run parameters differ:
Parameter |
Physics tier or observation level |
Platform requirement |
|---|---|---|
|
High-fidelity tier (Gazebo Sim lockstep; the only source of official results) |
d3-gz image |
|
Fast simulation tier (FleetSim; development, training and large-scale search; not ranked) |
The repository environment and the vehicle directory |
|
Kinematic development tier (development and tests only; not ranked) |
The repository environment |
|
L2 camera-in-the-loop observations; detections come from |
d3-sensorsvc image and a GPU (EGL rendering); the |
To run the episode from section 4 on the fast simulation tier, change only --physics on the platform side; the researcher-side commands are the same as in section 4.2:
PYTHONPATH=python:tools/sdk/anet4d/src python docs/sdk/examples/run_quickstart.py \
--spec configs/bench.d3/crop-handoff-001.l1-3uav.run_spec.json \
--worlds-root worlds --events-root d3data/events --physics fast \
--duration-s 60 --seed 1 --out runs/quickstart-1-fast --sock-root /tmp/d4d-sock
{"acts_sha256": {"uav-01": "5ecd1215126d4e78eaa5f394778721f6f7c42ddf83790e1a99efc7807d0238ab", "uav-02": "c9a4b1250911d9beb540ea16f3d3c860c2087f94e4dbeb73ec61969ca3eb9c97", "uav-03": "9aaa44f0ff0256b65a98d4f1634c066b45085be0253bab794ac606b9d13f7937"}, "duration_s": 60.0, "event": "crop-handoff-001", "n_ticks": 600, "obs_level": "L1", "physics": "fast", "reports": 0, "run_id": "quickstart-1", "schema": "drone4d.quickstart.summary.v1", "tier": "fast", "timeouts": {"uav-01": 0, "uav-02": 0, "uav-03": 0}, "wall_s": 39.23, "wire": {"uav-01": {"exited": null, "protocol_errors": 0}, "uav-02": {"exited": null, "protocol_errors": 0}, "uav-03": {"exited": null, "protocol_errors": 0}}, "world": "oryahovo-crop1"}
The fast and high-fidelity tiers use different dynamics models, so action streams are not expected to match across tiers; within a tier, two runs with the same seed are byte-identical. tests/d3/agentsdk_pkg/ installs the wheel in a temporary venv and runs the same plaza_watch.py on L1 episodes of the kinematic development tier and the fast simulation tier, on an L2 episode of the kinematic development tier (a CPU raster stand-in and the reference detector weights from the wheel), and on a high-fidelity episode inside the d3-gz image.
6. Baseline policies and the reference detector
Three baseline policies ship with the SDK as starting points for research. The sources live under tools/sdk/anet4d/ in the repository, and src/anet4d/ in the sdist anet4d-<version>.tar.gz is byte-identical to them:
Name |
Behavior |
Source |
|---|---|---|
|
One observation post per drone at the public anchors and the task area center; once in place, the gimbal sweeps a 3 × 3 grid |
|
|
The task area is split into one strip per drone and covered with lawnmower passes at 70% camera footprint overlap; the gimbal looks almost straight down; no communication |
|
|
Switches to tracking when a detection matches the brief appearance, broadcasts sightings and tracking claims every second, and hands a lost target to the nearest idle drone |
|
The shared part (takeoff and positioning, multi-target association, report rules and evidence) is in src/anet4d/baselines/common.py; the r6 reference rows are registered in src/anet4d/baselines/reference.py. All three baselines run on L1 and L2, two runs with the same seed produce byte-identical action streams, and every report carries evidence and passes bench/act.v1 validation. To connect a baseline instead of the example to the Env from section 4.1:
for u in uav-01 uav-02 uav-03; do
python -m anet4d.serve --baseline track_share --sock /tmp/d4d-sock/$u/agent.sock 2> $u.log &
done
wait
The reference detector ref_det_v1 inference and the L2 perception adapter are in src/anet4d/perception/ref_det.py; the frozen weights src/anet4d/perception/ref_det_v1.npz (sha256 da68c6cb3e91e51bd389aefd4b25e482301fa5633a0c6ecb6ebf7d5e16b584ce, verified on load) and the model card model_card.json ship in the wheel. The detector runs on the CPU only. The official L2 per-step wall-clock budget is 0.5 s (STEP_BUDGET_S); replaying a 360 s run of the L2 baseline in a std resource profile container (2 cores, 8 GB, no GPU, single-threaded BLAS) measured a worst step of 0.181 s (STD_STEP_WALL_S), which a custom agent can use to estimate its compute headroom.
7. Package the agent as an image
In an official evaluation, each drone's agent runs in its own isolated container (--network none, read-only root file system, non-root user, std resource profile with 2 cores, 8 GB and no GPU) and talks to the Env through the mounted /run/drone4d/agent.sock. An internal submission starts from the platform agent base image and adds its own package:
FROM d3-agent-py:dev
COPY plaza_watch.py /opt/agent/plaza_watch.py
ENV PYTHONPATH=/opt/drone4d:/opt/agent
CMD ["python", "-m", "anet4d.serve", "plaza_watch:PlazaWatch"]
See tools/bench/d3/examples/close_track/ for a complete example. The anet4d version inside the container comes from the base image; ranked runs accept images referenced by digest only.
8. Build the wheel and the sdist from source
Run from the repository root (the output goes to var/sdk/dist/ and no build directory is left in the source tree; setuptools 77 or later is required):
The wheel bytes depend on the build-time umask and on the permission bits of the source files, so set umask 022 and normalise the source permissions first; the sha256 below reproduces under these conditions (verified on 2026-10-25 for anet4d 0.3.2).
umask 022
rm -rf var/sdk && mkdir -p var/sdk && cp -r tools/sdk/anet4d var/sdk/src
chmod -R u=rwX,go=rX var/sdk/src
SOURCE_DATE_EPOCH=1760745600 python -m pip wheel --no-deps --no-build-isolation -w var/sdk/dist var/sdk/src
(cd var/sdk/src && SOURCE_DATE_EPOCH=1760745600 python -c "import setuptools.build_meta as b; b.build_sdist('../dist')")
ls var/sdk/dist
sha256sum var/sdk/dist/*.whl
anet4d-0.3.2-py3-none-any.whl
anet4d-0.3.2.tar.gz
7a5fe21c338a0846aecd1a56b1fc8efdeee93582763f46ac595ea86754e53eb9 var/sdk/dist/anet4d-0.3.2-py3-none-any.whl
The wheel is pure Python (py3-none-any) and contains all modules, the reference detector weights and the model card; with a fixed SOURCE_DATE_EPOCH, two builds produce byte-identical wheels. The sdist keeps file timestamps in its tar members, so its sha256 changes with the copy time and is not compared byte by byte. A wheel directory for offline installation needs anet4d and the following dependencies (numpy 2.4.6 for Python 3.11, since numpy 2.5 no longer supports Python 3.11):
Package |
Version |
Notes |
|---|---|---|
|
0.28.1, 1.0.9, 0.16.0, 4.15.1, 3.20, 2026.7.22, 4.16.0 |
Pure Python |
|
1.2.2 |
Per interpreter version (cp311, cp312, cp313) |
|
2.5.3 (2.4.6 for cp311), 11.3.0 |
The |
9. Troubleshooting
Symptom |
Cause and fix |
|---|---|
|
The Env was built on a host that has only |
|
The |
|
The platform image lacks the bench API client dependency. |
|
The wheel directory has no binary wheel for the interpreter version or the processor architecture. Check |
|
Not every agent connected within |
|
|
|
The fast simulation tier cannot find the vehicle directory. Run from the repository root, or point |
The gz export fails when the world directory is mounted read-only |
Point |
10. After this guide
You now have:
an installable
anet4denvironment and a reusable agent file;completed 3-drone L1 episodes on the high-fidelity tier (Gazebo Sim lockstep) and the fast simulation tier (FleetSim), with their run directories;
a way to check that wire-protocol and in-process runs are byte-identical;
the source locations of the three baseline policies and the reference detector, ready to modify.
Not yet covered:
ranked results: official evaluations run as benchmark jobs in isolated containers on dmax and reach the prototype board through internal submissions;
the platform-side environment for L2 camera-in-the-loop observations (d3-sensorsvc image and a GPU).