选择正确的执行 API

决策表

选择能够返回应用所需信息的最窄 API。所有选项最终都会进入同一个 Agent 引擎，区别只在于调用方保留多少控制权与执行证据。

**经验法则：**从 prompt_text 开始。当响应本身需要被检查时使用 prompt；当执行策略需要由应用控制时使用 run。

prompt_text

当应用只需要最终面向用户的回答时，使用 prompt_text。它会在需要时构建 Agent、创建便捷的根 Run，并在构建或执行失败时返回错误。

let answer = agent
    .prompt_text("总结这次部署的风险。")
    .await?;

这条便捷路径仍然使用 Runifold 的规范执行引擎，不会绕过轮次限制、已注册 Capability、重试策略或流式内容累积。

prompt

当你需要完整规范化结果而不只是文本时，使用 prompt。结果会保留 Transcript、详细用量、警告，以及无法无损标准化的服务商事件。

let outcome = agent
    .prompt("总结这次部署的风险。")
    .await?;
 
println!("tokens: {}", outcome.usage.tokens);
println!("answer: {}", outcome.text());

不要从文本或 HTTP Header 反推用量。应从规范结果中读取，让模型适配器保留 各服务商原生的记账细节。

stream

交互界面、长回答，以及需要在模型结束前处理事件的系统应该使用 stream。

流式响应不只是一串字符串。它还可能包含可见文本、推理、工具调用、用量、 警告、原始服务商事件与终止错误。必须消费到终止状态，才能保留完整用量和 重试安全信息。

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

run

当应用需要掌控执行策略时使用 run。调用方提供 RunContext，其中包含本次 操作真正需要的预算、Capability、截止时间、元数据与 Journal。

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?;

这是租户预算、请求截止时间、权限收窄、持久化 Journal 与共享运行树身份的 生产级执行边界。