Expand description
§bevy_agent_remote
JSON-RPC control for Bevy agent environments over HTTP, WebSocket, and stdio.
Part of bevy-agent. Requires Bevy 0.18.1 and Rust 1.91+. Version 0.0.4 is experimental; pin all companion crates to the same exact version.
[dependencies]
bevy_agent_remote = "=0.0.4"
bevy_agent_runner = "=0.0.4"§Serve a headless environment
use bevy_agent_remote::{HttpRemoteServer, JsonRpcBridge, RemoteSecurity};
use bevy_agent_runner::AgentApp;
fn serve(env: &mut AgentApp) -> anyhow::Result<()> {
let bridge = JsonRpcBridge::new(RemoteSecurity::default())?;
HttpRemoteServer::new("127.0.0.1:4000", bridge).serve(env)
}The server exposes POST /rpc, GET /health, and WebSocket JSON-RPC at GET /ws. Discovery methods expose the environment’s actions, observations, schemas, and capabilities.
For a rendered Bevy app, install BevyRemoteControlPlugin before app.run(). Network I/O runs separately while world mutations and primary-window captures remain on the Bevy main thread. Enable visual for primary-window screenshot support; software capture works headlessly when the game supplies a renderer.
§Remote access
Bind to loopback for local use. Configure a nonempty session token before exposing the listener beyond loopback. RemoteSecurity controls capabilities; filesystem access is disabled by default. Enable FILESYSTEM explicitly and set an artifact root when you need server-side captures or replay files.
Timed-out mutations return an operation ID. Retrieve the retained result with agent.operations.status; use a request retry_key to deduplicate retries after a lost response. The retry ledger belongs to one running HTTP/WebSocket server and expires with retained outcomes; stdio does not provide it.
§Connect a client
Install bevy_agent_cli to get the agentctl executable, then use a second terminal while your server is running:
cargo install bevy_agent_cli --version 0.0.4 --locked
agentctl info
agentctl action-space
agentctl reset --seed 42
agentctl observeInspect the action catalog before sending game-specific commands. The CLI walkthrough includes a complete sample server and explains the JSON-RPC response. Use the Python guide for a policy loop or other transports for WebSocket and stdio.
§Next steps
Read the guide for an organized walkthrough, examples, and troubleshooting.
Licensed under MIT OR Apache-2.0, at your option.
Structs§
- Agent
Capability - Bevy
Remote Control Plugin - Concurrent bounded networking with all Bevy mutations executed in
Update. Health and authenticated operation-status requests run outside the simulation pump, including while a callback runs or a primary-window capture is pending. - Http
Remote Server - Bounded concurrent networking with one serial simulation owner.
- Json
RpcBridge - Json
RpcError - Json
RpcRequest - Operation
Status - Operation
Status Params - Prepared
Request - A bounded, typed, authenticated request ready for its simulation owner. Parameter ownership is retained so executing it does not parse the payload again.
- Remote
Security - Remote
Server Limits - Fixed resource bounds for both headless and Bevy remote adapters.
- Remote
Server Status - Observable supervision state, also installed in Bevy apps.
Enums§
- Json
RpcResponse - Operation
State - RpcMethod
- The complete set of methods supported by the protocol.
Constants§
- MAX_
ACTIONS_ PER_ REQUEST - Maximum number of actions accepted in a single
agent.step_manycall. - MAX_
CAPTURE_ TIMEOUT_ FRAMES - Upper bound on asynchronous capture deadlines and watchdog lifetimes.
- MAX_
MESSAGE_ BYTES - Maximum complete JSON message size, including a stdio line delimiter.
- MAX_
TICKS_ PER_ REQUEST - Maximum number of ticks accepted in a single
agent.fast_forwardcall. - RPC_
AUTH_ ERROR - RPC_
INTERNAL_ ERROR - RPC_
INVALID_ PARAMS - RPC_
INVALID_ REQUEST - RPC_
METHOD_ NOT_ FOUND - RPC_
PARSE_ ERROR - JSON-RPC error codes used by this bridge.
- RPC_
REQUEST_ TIMEOUT - Deadline expiry or disconnected simulation owner, with operation correlation.
- RPC_
SERVER_ BUSY - Bounded connection, command, or operation admission is saturated.
Functions§
- agent_
action_ schema - agent_
action_ schema_ with_ custom_ actions - capability_
for_ observation_ mode - Capability needed to observe a given mode.
FullDebugStateandHybridexpose full state and requireOBSERVE_FULL_STATE; every other mode requires onlyOBSERVE_PLAYER. - custom_
action_ schema_ map - jsonrpc_
error_ schema - jsonrpc_
request_ schema - jsonrpc_
response_ schema - method_
params_ schema - Discoverable parameter contracts are generated from the decoded DTOs. Game catalogs narrow the generated action and observation definitions.
- mutation_
failure_ schema - Structured error data emitted after reset or step mutation has begun.
- observation_
schema - observation_
schema_ with_ catalog - operation_
status_ schema - reset_
response_ schema - reset_
response_ schema_ with_ catalog - rpc_
method_ schema - step_
many_ response_ schema - step_
many_ response_ schema_ with_ catalog - step_
response_ schema - step_
response_ schema_ with_ catalog - supported_
action_ names - timeout_
frames_ to_ duration - Convert frame-count timeouts to a wall-clock deadline (60 fps assumption).
- visual_
capture_ schema