Skip to main content

Crate bevy_agent_remote

Crate bevy_agent_remote 

Source
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 observe

Inspect 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§

AgentCapability
BevyRemoteControlPlugin
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.
HttpRemoteServer
Bounded concurrent networking with one serial simulation owner.
JsonRpcBridge
JsonRpcError
JsonRpcRequest
OperationStatus
OperationStatusParams
PreparedRequest
A bounded, typed, authenticated request ready for its simulation owner. Parameter ownership is retained so executing it does not parse the payload again.
RemoteSecurity
RemoteServerLimits
Fixed resource bounds for both headless and Bevy remote adapters.
RemoteServerStatus
Observable supervision state, also installed in Bevy apps.

Enums§

JsonRpcResponse
OperationState
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_many call.
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_forward call.
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. FullDebugState and Hybrid expose full state and require OBSERVE_FULL_STATE; every other mode requires only OBSERVE_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