Repository navigation
Agent API
inksong edited this page Nov 9, 2026
·
2 revisions
- Every aircraft has at most one controller at a time.
- An agent opens a session (a lease it renews) and claims aircraft.
- A person who possesses an aircraft always wins. The claim is suspended, every control call returns
possessed_by_human, and on release the agent receivesrelay_handbackand decides what to do next. - Stop and Stop all never change who controls an aircraft.
| Level | Agents may use |
|---|---|
Sticks only (sticks, default) |
Sticks (50 Hz WebSocket stream, single frames, timed sticks skill), arm and disarm, manual modes (STABILIZE, MANUAL, ACRO), fire, onboard programs, emergency stop and land as a safety action |
Full (full) |
Everything, including take-off, hold, move, turn, go-to, return, velocity and attitude skills, sequences and re-fly |
High-level calls at sticks return 403 sticks_only on REST, WebSocket and MCP alike. Only the operator can change the level, in Settings → Safety. The operator's own controls are never limited by it.
| Interface | Address |
|---|---|
| REST |
http://127.0.0.1:8765/api/v1 (first free port from 8765 to 8775) |
| WebSocket |
ws://127.0.0.1:8765/api/v1/stream: fleet snapshots at 10 Hz, arena at 20 Hz, events as they happen, sticks in |
| OpenAPI |
http://127.0.0.1:8765/openapi.json, interactive at /docs
|
| Python SDK |
sdk/python/anet_relay_client.py (standard library only) and examples |
| MCP | three stdio servers, see MCP Servers |
The API listens on the loopback interface only.
from anet_relay_client import RelayClient
with RelayClient() as relay: # http://127.0.0.1:8765, or set RELAY_API
relay.open_session("my-agent")
relay.claim("sim-1")
relay.mode("sim-1", "STABILIZE")
relay.arm("sim-1")
for _ in range(100): # 2 s of sticks at 50 Hz
relay.sticks("sim-1", roll=0, pitch=0, yaw=0, throttle=0.55)For anything that must hold the aircraft steady, deploy an onboard program instead of streaming sticks from the agent.
| Area | Highlights |
|---|---|
| Fleet | Vehicles, telemetry, parameters, simulators (POST /sims with engine: "relay" or "sitl"), frames, hover assist, airframe defects |
| Firmware twins and HITL | Autopilot packs, firmware identification, twin profiles, twin status, serial ports and links, hardware in the loop (/vehicles/{id}/hitl) |
| Control | Sessions, claims, sticks, skills, sequences, re-fly, stop |
| Device level | Any MAVLink message, parameters, command catalogue, single-motor tests, actuators, RC override, message rates, calibration, reboot, termination (confirm words) |
| Application | Language, workspace, selection, network scan, settings, controllers, records, screenshots (needs Allow agents to operate Relay) |
| Programs | Programs, revisions, tests, deploy, live params, logs, challenges, duels, ladder |
| Arena | Fire, arena view, dogfights, matches, leaderboard |
| Bench and health | Bench procedures and rolling flight-health diagnostics |
| Events | Dozens of event kinds, from relay_handback to collision and match_finished
|
The complete reference, with every route, field, event and error, is the Agent API guide.
Use the same calls. A real aircraft additionally requires the operator's preflight steps and confirm: "ARM" on arm, and programs need the operator's per-aircraft permission. See Real Aircraft.
Get started
Simulation
- Simulator and Physics
- Collisions and Rings
- Firmware Twins and HITL
- PX4 and ArduPilot SITL
- Simulators Compared
Arena
Programs and agents
Tools
Help