Struct StepflowClient 

pub struct StepflowClient { /* private fields */ }

High-level client for interacting with the Stepflow orchestrator.

Wraps the gRPC service clients for flows, runs, health, and component discovery, providing a convenient API for common operations.

Example

use stepflow_client::{StepflowClient, FlowBuilder, ValueExpr};

let mut client = StepflowClient::connect("http://localhost:7840").await?;

let mut builder = FlowBuilder::new();
builder.add_step("hello", "/builtin/eval", ValueExpr::null());
let flow = builder.output(ValueExpr::step_output("hello")).build()?;

let flow_id = client.store_flow(&flow).await?;
let output = client.run(&flow_id, serde_json::json!({"name": "world"})).await?;
println!("{output}");

Implementations

impl StepflowClient

pub async fn connect(url: impl Into<String>) -> ClientResult<Self>

Connect to the Stepflow orchestrator at the given URL.

The URL should be in the form http://host:port (or https://... for TLS).

pub async fn store_flow(&mut self, flow: &Flow) -> ClientResult<String>

Store a flow definition in the orchestrator, returning its flow ID.

The returned flow ID can be passed to run or submit.

pub async fn run(&mut self, flow_id: &str, input: Value) -> ClientResult<Value>

Execute a flow synchronously, blocking until it completes, and return the output.

This is equivalent to submit + waiting for the run to complete.

pub async fn submit( &mut self, flow_id: &str, input: Value, ) -> ClientResult<String>

Submit a flow for asynchronous execution, returning the run ID.

Use get_run to poll for completion and get_run_items to fetch outputs.

pub async fn get_run( &mut self, run_id: &str, wait: bool, ) -> ClientResult<RunStatus>

Get the status of a run.

If wait is true, the request will block until the run completes (or fails).

Note: outputs are not included in the response — use get_run_items to fetch them after the run completes.

pub async fn get_run_items(&mut self, run_id: &str) -> ClientResult<Vec<Value>>

Get the output of each item in a completed run.

Returns one serde_json::Value per input item, in submission order. Errors for individual items are currently surfaced as ClientError::InvalidResponse.

pub async fn list_components( &mut self, exclude_schemas: bool, ) -> ClientResult<ListComponentsResult>

List all components registered across all plugins.

Set exclude_schemas to true to omit JSON Schemas from the response (faster when you only need component paths and descriptions).

Note: this triggers on-demand component discovery from all plugins and may take a moment if workers haven’t connected yet.

pub async fn status_events( &mut self, run_id: &str, include_sub_runs: bool, include_results: bool, ) -> ClientResult<StatusEventStream>

Stream execution events for a run.

Returns a server-streaming response that emits stepflow_proto::StatusEvents as the run progresses. Drive the stream with stream.message().await.

Set include_sub_runs to also receive events from nested sub-flows. Set include_results to include step outputs in completion events.

Example

let mut stream = client.status_events(run_id, false, false).await?;
while let Some(event) = stream.message().await? {
    println!("{event:?}");
}

pub async fn get_flow_variables( &mut self, flow_id: &str, ) -> ClientResult<HashMap<String, FlowVariable>>

Get the variable definitions declared in a flow.

Returns a map of variable name → FlowVariable describing the schema, default value, and optional environment variable mapping for each variable.

pub async fn is_healthy(&mut self) -> bool

Check whether the orchestrator is healthy.