riceprompt-engine: YAML-Native Agent Workflow Engine in Rust

What Problem riceprompt-engine Solves

Building an LLM agent that does more than call a single model usually requires wiring together multiple concerns: routing across providers, chaining node outputs as inputs to the next step, running transformation scripts, querying databases for context, and handling retries and streaming. Most existing solutions bundle that logic into a framework written in Python or TypeScript, which means a Rust project either wraps a foreign runtime or duplicates the work.

riceprompt-engine provides a YAML-native workflow definition and a Rust execution core so the entire workflow (graph topology, prompts, provider credentials, data source queries, MCP tool calls) lives in a single declarative file. The engine parses it, resolves dependencies, and runs the graph asynchronously. The target audience is Rust developers building agent pipelines who want a structured, file-driven approach rather than imperative code, and teams using the RicePrompt visual IDE who need to embed or extend the same execution engine programmatically.

YAML Workflow Format and Node Types

A workflow file declares a version string, a name, providers (with API keys), a list of nodes, edges between them, and templates for prompts. The authoritative specification is docs/FLOW_SPEC.md in the repository. A minimal three-node workflow looks like this:

version: "1.0"
name: "hello_world"

providers:
  openai:
    api_key: "${OPENAI_API_KEY}"

nodes:
  - id: start
    type: start

  - id: greet
    type: generate
    config:
      provider: openai
      model: gpt-4o-mini
      template: tpl_greet
      variables:
        name: "start.name"

  - id: response
    type: response
    config:
      output:
        greeting: "greet.output"

Edges declare data flow between node ids. Templates declare user prompts with Handlebars-style variable substitution.

The engine ships several node types beyond generate. The transform node runs Rhai scripts for data manipulation. The iterator node loops over a collection. The supervisor node routes work across multiple sub-agents. The subgraph node embeds one workflow inside another. The data_connector node queries external storage. The skill_set node provides progressive-disclosure knowledge bundles. The mcp and mcp_tools nodes integrate Model Context Protocol tools.

Embedding riceprompt-engine in a Rust Project

The crate is published on crates.io as riceprompt-engine. Add it to Cargo.toml:

[dependencies]
riceprompt-engine = "0.1"

The engine exposes a builder-pattern entry point. The following example from the README loads a YAML file, builds the engine, and runs the workflow with an input JSON object:

use riceprompt_engine::Engine;
use serde_json::json;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let yaml = std::fs::read_to_string("hello.yaml")?;
    let engine = Engine::builder().build()?;
    let result = engine.run_yaml(&yaml, json!({ "name": "Ada" })).await?;
    println!("{}", serde_json::to_string_pretty(&result)?);
    Ok(())
}

The engine returns an ExecutionResult that can optionally include the source YAML, so downstream tooling can render the workflow topology alongside per-node results from a single file. The examples/ directory in the repository contains runnable examples covering tool calling, MCP integration, harness write-back, search, and the skill_set node type.

Supported LLM Providers and Data Connectors

The README lists eleven providers: OpenAI, Anthropic, Gemini, DeepSeek, Qwen, Zhipu, Moonshot, MiniMax, xAI, Huoshan, and any OpenAI-compatible endpoint. Provider credentials are declared in the workflow YAML under the providers key, with API keys read from environment variables using ${VAR} syntax.

The Cargo.toml dependency list shows the built-in data connectors: PostgreSQL via tokio-postgres and deadpool-postgres, MySQL via mysql_async, MongoDB via the mongodb crate, Redis with the json and connection-manager features, Qdrant as a vector database client, and S3-compatible object storage via the AWS SDK. Templating uses Handlebars. Transform node scripting uses the Rhai embedded scripting engine.

The harness layer injects workflow-level instructions (described in the README as analogous to a CLAUDE.md file) into every generate node and supports persistent memory across calls.

Harness Layer and Skill Sets

One feature that distinguishes riceprompt-engine from simpler chaining libraries is the harness layer. A workflow can declare workflow-level instructions that are injected into every generate node in the graph, similar in concept to a system prompt that applies across all LLM calls in the run. The README describes this as analogous to a CLAUDE.md file. Combined with persistent memory support, the harness layer lets a workflow maintain shared context across all its LLM calls without explicitly threading it through every node's template.

The skill_set node type implements what the README calls progressive-disclosure knowledge bundles: structured knowledge that is made available to the agent incrementally rather than all at once. The README does not elaborate further on the skill_set mechanism, so the full behavior requires reading docs/FLOW_SPEC.md. The ExecutionResult type can carry the source YAML alongside the per-node results, which means a caller can render the workflow topology and its output from one returned value without keeping a separate reference to the original file.

Checkpoint and Resume Behavior

Long-running workflows face a practical problem: a failure midway means restarting from the beginning and re-paying for all the LLM calls that already succeeded. The README lists checkpoint and resume as a first-class feature: the engine can pause a workflow and resume it from the last checkpoint rather than from the start.

The README does not document the checkpoint storage format or the exact API surface for pausing and resuming. For workflows where individual steps are expensive (a large database query, a slow LLM call, a chain of sub-agent delegations), the absence of that documentation is a gap to verify against docs/FLOW_SPEC.md before relying on it in production. The async execution model is built on Tokio, so the engine is well-suited to workloads that issue many concurrent I/O calls, such as a workflow that queries multiple databases in parallel before generating a summary.

API Stability and Project Status

The crate is at version 0.1.0. The README states explicitly that the API may change between minor versions while the spec stabilizes, and recommends pinning an exact version if stability is needed. The repository has no GitHub releases; all versioning is through crates.io.

The last push to the repository was on 2026-04-28. The project is not archived. There are no published benchmarks, no performance claims, and no documented migration path between 0.1.x versions. Contributing guidelines ask for cargo fmt and cargo clippy --all-targets before pull requests, and for FLOW_SPEC.md to be updated in the same pull request as any change to the YAML surface.

Compared to Temporal for Agent Workflow Orchestration

Temporal is a durable execution platform written in Go that orchestrates long-running workflows with built-in retry, timeout, and state-persistence primitives. It is language-agnostic through client SDKs and is deployed as a separate server process. riceprompt-engine is a Rust library that runs in-process without an external orchestration server, and its workflow definition is a static YAML file rather than code written against an SDK.

That difference shapes the trade-offs. Temporal gives proven durability guarantees, a UI for inspecting running workflows, and a large ecosystem, at the cost of operational complexity and a non-YAML programming model. riceprompt-engine gives a single-file, declarative workflow with no server to deploy, but with a 0.1.x API that is still changing. For teams already running Temporal and adding LLM calls to existing workflows, Temporal's LLM activity wrappers are the natural path. For teams starting a new Rust project centered on LLM agent graphs and willing to accept an unstable API, riceprompt-engine is worth evaluating.

Editorial conclusion

riceprompt-engine is worth evaluating for Rust projects that need a declarative, file-driven way to compose multi-step LLM agent workflows across several database and API backends. It is a poor fit for teams that need a stable, production-ready API today: the crate is at 0.1.x and the README explicitly warns that the API may change between minor versions. Before adopting it, pin an exact version in Cargo.toml and review docs/FLOW_SPEC.md to confirm the node types and provider names match your stack.

Frequently asked questions

Official sources

1. Issues
2. jieyefriic/rp-engine on GitHub
3. License: Apache-2.0
4. Project website
5. README