第一次可信运行

你将构建什么

你将创建一个由 OpenAI 驱动的小型 Agent，执行一次 Prompt，并理解其中涉及的执行层。示例是完整的：可以直接复制到新项目运行，不需要补充被省略的应用代码。

前置条件

Rust 1.88 或更新版本
服务端进程能够读取 OpenAI API Key
OpenAI 项目有权访问的模型

Runifold 目前处于预览阶段。需要可复现构建的应用应固定 crate 版本，并在升级前阅读 Changelog。

创建项目

创建二进制 crate，并且只启用需要的模型服务商：

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 把运行时门面与具体 Provider Adapter 分开：runifold 提供 Agent、 Tool 与 Workflow，runifold-providers 只编译通过 Feature 选中的协议适配器。

在进程环境中设置凭证：

export OPENAI_API_KEY="your-api-key"

长期有效的模型凭证应该留在服务端。浏览器或边缘应用应该调用自己控制的应用网关，而不是把 API Key 写入 WASM 或 JavaScript。

运行 Agent

用下面的完整程序替换 src/main.rs：

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(())
}

运行：

cargo run

具体回答会随模型变化，但程序应该正常退出并输出一段文本。如果当前项目使用其他模型，只需修改传给 runtime 的字符串。

理解执行路径

这段简洁程序仍然建立了一条完整执行路径：

OpenAiClient 负责认证与传输协议。
runtime("gpt-5") 加入安全重试路由与熔断器。
agent("assistant") 创建模型与工具的执行边界。
prompt_text 创建便捷的根 Run，并返回可见文本。

便捷 API 并不是第二套简化引擎。之后可以向同一个 Agent 提供显式 RunContext，逐步加入预算、Capability、截止时间、元数据与 Journal。

常见问题

现象	可能原因	处理方式
找不到 `OPENAI_API_KEY`	当前 Shell 没有导出变量	在运行 Cargo 的终端重新 export
HTTP 401	凭证无效或已撤销	创建新 Key 并更新环境变量
model not found	项目无权访问 `gpt-5`	改用当前项目可用的模型
找不到 `runifold_providers` 或 `openai`	未添加 Provider Crate 或 Feature	执行 `cargo add runifold-providers@0.9.0 --features openai`
请求超时	网络、服务商或应用截止时间	先检查错误类型，再决定是否重试

不要无条件重试所有失败。Runifold 只重试适配器明确标记为安全的错误；不确定失败可能已经消耗 Token，甚至已经产生外部副作用。

遇到编译、凭证、Capability、流式输出或恢复问题，请使用完整的故障排查指南。