Skip to main content

Crate rusty_worker

Crate rusty_worker 

Source
Expand description

§rusty-worker

The worker-side SDK for rusty-agent-runtime remote node execution: one Node trait, remote impls behind the same trait. A worker is just an HTTP service that hosts Node handlers by name; a graph node registered as rusty_agent_runtime::remote::RemoteNode calls into it transparently.

§Endpoints

  • POST /execute — accepts a JSON NodeTask, dispatches to the handler registered under NodeTask::node, and replies with a JSON NodeTaskResponse:
    • Ok(output) → { "output": ... }
    • Err(interrupt) → { "interrupt": <value> } (HITL across the wire)
    • Err(e) → { "error": "<message>" }
  • GET /ok — liveness + capability probe: protocol version and the registered handler names.

§Registering handlers

WorkerRegistry::register accepts anything that implements Node — which, thanks to the blanket impl in the core crate, includes ordinary async closures Fn(NodeContext) -> impl Future<Output = Result<NodeOutput>>, named Node impls, and Arc<dyn Node>.

use rusty_agent_runtime::prelude::*;
use rusty_worker::{serve, WorkerRegistry};

let mut registry = WorkerRegistry::new();
registry.register("greeter", |ctx: NodeContext| async move {
    let name = ctx
        .state()
        .get("name")
        .and_then(|v| v.as_str())
        .unwrap_or("world")
        .to_string();
    Ok(NodeOutput::update("greeting", serde_json::json!(format!("hello, {name}!"))))
});

serve(registry, "127.0.0.1:8200").await

On the graph side, point a RemoteNode at the same handler name:

ⓘ
builder.add_node("greeter", RemoteNode::new("greeter", "http://127.0.0.1:8200"));

§Error semantics across the wire

Handler errors are flattened to a message string in NodeTaskResponse::error and arrive client-side as RustyError::Node, which the executor treats as a hard failure — the retryable classes (Llm, Tool) do not survive the wire. A remote node whose transient failures should be retried must therefore rely on transport-level retry (connection/timeout/5xx on the client) or surface retryable outcomes through its own protocol on top of extra.

§Durable activities (R0.6)

ActivityWorker is the pull-based counterpart to serve: it claims leased tasks (kind + JSON payload) from the rusty-agent-server task queue (POST /tasks/claim), executes the activity::Activity registered for the task’s kind while a background heartbeat renews the lease every lease / 3, and settles with complete or a classified fail. Lease loss (409) aborts the activity via a CancellationToken, and cancelling the shutdown token drains the worker: claiming stops, the in-flight activity settles within a bounded grace (default activity::DEFAULT_DRAIN_GRACE), and an attempt that outlives the grace is aborted and left for the server to reassign at lease expiry. See the activity module for the protocol and semantics.

Re-exports§

pub use activity::Activity;
pub use activity::ActivityCompletion;
pub use activity::ActivityContext;
pub use activity::ActivityWorker;

Modules§

activity
Durable activities (R0.6): ActivityWorker, the leased-task execution loop against the rusty-agent-server task queue.

Structs§

WorkerRegistry
The registry of named node handlers a worker serves.

Functions§

probe_body
Convenience JSON body for quick manual probes (curl examples in docs).
router
Build the axum Router for a registry (POST /execute + GET /ok).
serve
Serve a registry on addr until the process is stopped.