Choose the right execution API

Decision table

Choose the narrowest API that returns the information your application needs. Every option reaches the same Agent engine; the difference is how much control and evidence the caller retains.

Rule of thumb: begin with prompt_text. Move to prompt when the response itself matters, and to run when execution policy matters.

prompt_text

Use prompt_text in application code that only needs the final user-visible answer. It builds the Agent if necessary, creates an ergonomic root run, and returns an error if either construction or execution fails.

let answer = agent
    .prompt_text("Summarize the deployment risk.")
    .await?;

This convenience path still uses Runifold's canonical execution engine. It does not bypass turn limits, registered capabilities, retries, or streaming accumulation.

prompt

Use prompt when you need the canonical outcome rather than only its text. The outcome preserves the transcript, detailed usage, warnings, and provider-specific events that cannot be normalized without loss.

let outcome = agent
    .prompt("Summarize the deployment risk.")
    .await?;
 
println!("tokens: {}", outcome.usage.tokens);
println!("answer: {}", outcome.text());

Do not reconstruct usage from text or HTTP headers. Read it from the canonical outcome so provider adapters can preserve their native accounting detail.

stream

Use stream for interactive interfaces, long-running answers, and systems that need to react to events before the model finishes.

Streaming is more than a sequence of strings. A stream can contain visible text, reasoning, tool calls, usage, warnings, raw provider events, and a terminal error. Keep consuming until the terminal state so usage and retry safety are not lost.

let mut events = agent.stream(input, &run);
 
while let Some(event) = events.next().await {
    handle_event(event?);
}

run

Use run when the application owns execution policy. Supply a RunContext with the exact budget, capabilities, deadline, metadata, and journal required for this operation.

let run = RunContext::root(
    BudgetTracker::new(Budget {
        tokens: Some(8_000),
        turns: Some(6),
        tool_calls: Some(4),
        ..Budget::default()
    }),
    capabilities,
);
 
let outcome = agent.run(input, &run).await?;

This is the production boundary for tenant budgets, request deadlines, capability attenuation, durable journaling, and shared run-tree identity.