Crate flux_sdk 

flux-sdk — the high-level library API.

Wraps the flux-flow engine, built-in tools, the safety envelope, and a session into a small Client. You supply a Provider (from flux-providers) and a workspace root; the SDK wires the rest.

There are three front doors: Client (an adaptive agent turn driven by an authored Flux-Lang outer loop, returning a TurnOutput), FlowClient (the authored Flux-Lang parse → analyze → execute lifecycle), and the dsl (author the AST in Rust). Client assembles flux_flow::engine::FlowEngine; FlowClient delegates directly to the same flux-flow runtime adapter, store, and safety envelope for one-flow execution. Each door has a runnable, no-API-key example: examples/client_basic.rs, examples/parameterized_flow.rs, and examples/dsl_loops.rs respectively. On top of the DSL, recipes is a cookbook of reusable, parameterized flow builders (routing, lookup, the loop family, resilience).

// Runnable hermetic version: `cargo run -p codewandler-flux-sdk --example client_basic`.
use flux_sdk::Client;
let provider = Box::new(flux_providers::anthropic::anthropic_from_env()?);
let client = Client::builder().auto_approve(true).build(provider, ".")?;
let out = client.run("Summarize the README").await?;
println!("{}", out.text);

Re-exports

pub use events::AgentEvent;

pub use events::FlowStream;

pub use events::TurnStream;

pub use flow::assemble_registry;

pub use flow::ExecutionResult;

pub use flow::FlowClient;

pub use flow::FlowClientBuilder;

pub use session::Fork;

pub use session::Session;

pub use storage::Storage;

Modules

approval

Approval policy. Implement Approver and pass it to a builder’s approver(...) to gate ops with your own logic; ApprovalChoice is your verdict, IntentSet is the per-call intent your request receives, and RiskApprover is a ready-made risk-tiered policy.

authorization

Authorization floor. Every SDK executor carries an [ExecutionAuthorization] profile. Builders use [ExecutionAuthorization::local] by default; embedding services should install a resolved policy and identity with with_authorization(...).

dsl

The Rust embedded DSL for authoring flows — builder primitives that construct the Flux-Lang AST. Build a flux_lang::ast::DraftAst with dsl::Flow/dsl::Block (loops and control-flow are first-class), then drive it through FlowClient::analyze + FlowClient::execute. Re-exported from flux-lang so consumers can stay inside flux_sdk. See examples/dsl_loops.rs. A Rust embedded DSL for authoring Flux-Lang flows — builder primitives that compile straight down to the crate::ast tree, so a Rust programmer can write a flow natively instead of emitting JSON or natural language.

events

Owned streaming events — the async-iterator shape of a turn.

flow

The Flux-Lang lifecycle surface — the SDK front door for authored deterministic flows.

observe

Session observability. The projection types Session readers return — Message (history), TurnSummary (turns), RunEvent (run_trace), ModelCost (cost), and EfficiencySummary (efficiency) — plus the stores Storage::custom accepts and the evidence-gated surfacing types ClientBuilder::groups takes.

recipes

Reusable Flux-Lang flow recipes — a cookbook of small, parameterized builders that compile to a DraftAst out of the DSL primitives.

session

The resumable session handle.

storage

Where a client’s sessions live — the storage seam.

subagents

Sub-agents. Attach named roles to a conversational client with ClientBuilder::with_sub_agents (or to a flow client with FlowClient::with_sub_agents); a turn whose native stage calls task(role, …) then delegates to a role’s child agent through the same authorization → approval → guarded-IO envelope. SubAgents is the bundle (roles + the child tool surface + a ProviderFactory + limits), SpawnLimits bounds each child (tokens, wall-clock, …), and Role/RoleRegistry name the roles a task may target (try_parse_role builds a Role from a markdown definition while rejecting malformed capability metadata).

tools

Custom tools. Implement Tool — or build one from a closure with tool_fn/FnTool — and register it with ClientBuilder::register_op/FlowClient::register_op. A registered tool dispatches through the same authorization → approval → guarded-IO envelope as every built-in. ToolSpec (with Risk) describes the tool to the model and the envelope; ToolContext/ToolResult are the dispatch types; ToolRegistry is what a register_pack closure receives.

voice

Voice. The types the two voice front doors take — Session::run_voice_flow (flow-driven: the flow leads, the model is speech I/O) and FlowClient::run_voice_session (model-driven: the model leads and calls tools). Implement VoiceSink to receive audio / transcripts / lifecycle; VoiceReply is a flow turn’s spoken reply (Continue/Complete); RealtimeProvider + RealtimeConfig are the full-duplex provider seam (a concrete one lives behind flux-providers’ realtime feature).

Structs

AdaptiveLoopPolicy

The agent definition (ClientBuilder::from_spec) plus its permission rules. Re-exported so the full-control door needs no direct flux-agent dependency. Cognition policy for one logical adaptive run. The total call ceiling spans intent repair, exploration, and every durable decision resume.

AgentExecutorConfigDeprecated

Surface-owned inputs used when AgentSpec constructs its guarded Executor.

AgentSpec

The agent definition (ClientBuilder::from_spec) plus its permission rules. Re-exported so the full-control door needs no direct flux-agent dependency. A first-class agent definition: model, persona, skills, tool selection, permissions, and the turn settings — everything that distinguishes one agent from another. Assemble it into a running FlowEngine with AgentSpec::assemble (the simple path) or AgentSpec::into_engine (when the surface builds its own richly-configured Executor).

AgentStagePolicy

The agent definition (ClientBuilder::from_spec) plus its permission rules. Re-exported so the full-control door needs no direct flux-agent dependency. Optional overrides for one built-in adaptive model stage. Missing values inherit the agent’s provider-local model, effort, and token setting.

CancellationToken

Cancels a running turn (Session::send_with) or voice session — re-exported from tokio-util so consumers don’t need the direct dependency. A token which can be used to signal a cancellation request to one or more tasks.

Client

A configured agent (runs on FlowEngine): the expensive, long-lived half of the SDK’s conversational door. Conversations are Session handles — a fresh default one is created at build (so Client::run works out of the box), and Client::create_session / Client::open_session / Client::latest_session manage the rest. With persistent Storage, sessions — and their suspended flows — survive the process.

ClientBuilder

Builder for a Client. Internally an AgentSpec plus the shared envelope knobs, so every agent-definition field has exactly one home and from_spec is the full-control escape hatch rather than a parallel path.

Permissions

The agent definition (ClientBuilder::from_spec) plus its permission rules. Re-exported so the full-control door needs no direct flux-agent dependency. Pre-allow/deny rules an agent’s executor starts with (the rest gate through the approver).

PricingTable

The model rate table Session::cost prices a session against. PricingTable::builtin is the curated default; the optional pricing feature adds [pricing::load_pricing_table] to overlay a user’s ~/.flux/pricing.toml. A price book: model id → per-tier Rates. Build the curated defaults with PricingTable::builtin, then optionally fold user overrides on top with PricingTable::apply_override.

ReplayReport

The report Session::replay returns — the replayed plans, a divergence diagnostic (None on a faithful replay), and cassette-cell accounting. Re-exported from flux-flow. The outcome of a hermetic session replay.

Sandbox

The OS-sandbox posture types, re-exported so a consumer can inject an explicit sandbox into a builder via ClientBuilder::with_sandbox/flow::FlowClientBuilder::with_sandbox without taking a direct flux-system dependency. The resolved sandbox for this process: settings plus the backend resolve() picked. The one seam crate::System::build_command wraps through.

SandboxSettings

The OS-sandbox posture types, re-exported so a consumer can inject an explicit sandbox into a builder via ClientBuilder::with_sandbox/flow::FlowClientBuilder::with_sandbox without taking a direct flux-system dependency. The resolved sandbox posture for this process: mode, network policy, and any extra writable paths layered on top of SpawnPolicy::for_workspace’s defaults.

TurnOutput

The result of one turn — a Client::run, a Session::send, or a Session::start_flow.

Usage

The per-turn token accounting carried on TurnOutput. Re-exported from flux-core. Token accounting for a single provider turn.

Enums

AgentLoopSpec

The agent definition (ClientBuilder::from_spec) plus its permission rules. Re-exported so the full-control door needs no direct flux-agent dependency. The outer control program for an agent turn.

BuiltinAgentLoop

The agent definition (ClientBuilder::from_spec) plus its permission rules. Re-exported so the full-control door needs no direct flux-agent dependency. A shipped agent-loop preset. Presets are ordinary Flux-Lang programs selected explicitly by an agent definition; the host does not probe the workspace for an implicit override.

Traits

AgentSink

The engine’s streaming contract — implement it and pass it to Session::send_with to receive a turn’s deltas, tool calls, tool results, and observations as they happen (or use Session::stream for the owned-event shape). Re-exported from flux-flow. Receives streaming output and tool activity from a turn (the CLI/TUI/SDK implements this).

Provider

The provider trait — the one construction argument every client’s build takes. The concrete backends live in flux-providers (Anthropic/OpenAI/OpenRouter/Ollama/Bedrock + the subscription providers); a consumer implements this for a mock, or adds flux-providers for a real one. An LLM provider capable of streaming a response.

Functions

stage_fn

Build a typed, closure-backed stage operation. I and O are independent contracts: both JSON Schemas are derived and registered, the Flux analyzer infers O at call sites, and execution still traverses the ordinary authorization/approval dispatcher. The safe default is a low-risk, idempotent read stage; use a bespoke tools::Tool when the stage has effects or permission subjects that need a stronger contract.