Skip to content

Agent API

inksong edited this page Nov 9, 2026 · 2 revisions

Agent API

Agents workspace: sessions, claims, recent calls and interface addresses

Control model

  • 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 receives relay_handback and decides what to do next.
  • Stop and Stop all never change who controls an aircraft.

Agent flight level

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.

Interfaces

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.

Minimal agent

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.

What is in the API

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.

Moving to a real aircraft

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.

Clone this wiki locally