Your first trustworthy run

What you will build

You will create a small OpenAI-backed Agent, run one prompt, and understand the execution layers involved. The example is intentionally complete: you can paste it into a new project and run it without filling in omitted application code.

Prerequisites

• Rust 1.88 or newer
• an OpenAI API key available to the server process
• a model your OpenAI project can access

Runifold is pre-alpha. Pin the crate version in applications that need reproducible builds, and review the changelog before upgrading.

Create the project

Create a binary crate and enable only the provider you need:

cargo new hello-runifold
cd hello-runifold
cargo add runifold@0.9.0
cargo add runifold-providers@0.9.0 --features openai
cargo add tokio --features macros,rt-multi-thread

Runifold 0.9 separates the runtime facade from concrete Provider adapters. runifold supplies Agents, Tools and workflows; runifold-providers compiles only the protocol adapters selected by its Features.

Set the credential in the process environment:

export OPENAI_API_KEY="your-api-key"

Long-lived provider credentials belong on the server. Browser and edge applications should call an application-owned gateway instead of embedding the key in WASM or JavaScript.

Run the Agent

Replace src/main.rs with:

use runifold::ProviderModelExt;
use runifold_providers::openai::OpenAiClient;
 
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let runtime = OpenAiClient::from_api_key(
        std::env::var("OPENAI_API_KEY")?
    )?
    .runtime("gpt-5")?;
 
    let answer = runtime
        .agent("assistant")
        .system("Answer precisely and expose uncertainty.")
        .prompt_text("Why is durable execution useful?")
        .await?;
 
    println!("{answer}");
    Ok(())
}

Run it:

cargo run

The exact answer varies by model, but the process should exit successfully and print one text response. If your account uses another model, change only the string passed to runtime.

Understand the path

The concise program still creates a complete execution path:

1. OpenAiClient owns authentication and wire-protocol behavior.
2. runtime("gpt-5") adds retry-safe routing and a circuit breaker.
3. agent("assistant") creates the model-tool execution boundary.
4. prompt_text creates an ergonomic root Run and returns visible text.

The convenience API does not implement a second, simplified engine. Later you can supply an explicit RunContext to the same Agent to add budgets, capabilities, deadlines, metadata, and a journal.

Troubleshooting

Do not blindly retry every failure. Runifold retries only errors the adapter marks as safe; an ambiguous failure may already have consumed tokens or produced an external effect.

For compilation, credentials, capability, streaming, or recovery failures, use the complete Troubleshooting guide.