构建并配置 Agent

Agent 的组成

Agent 由模型、可信指令、可选上下文、可调用工具和子 Agent，以及本地执行策略组成。它不会拥有环境中的隐式凭证、隐藏的记忆后端或无限循环。

let agent = runtime
    .agent("support")
    .system("Answer only from relevant evidence.")
    .max_turns(6);

Agent 名称是事件和诊断信息中的执行身份。应该使用 support、triage 或 invoice-review 这类稳定的应用名称，而不是随机请求 ID。

Builder 与验证

流式 Builder 会保留注册错误，直到调用 build。因此工具和子 Agent 可以保持链式注册，同时不会静默覆盖重复名称。

let agent = runtime
    .agent("support")
    .system("Be concise.")
    .max_turns(6)
    .build()?;

便捷路径可以直接在 Builder 上调用 prompt 或 prompt_text，由它完成构建与运行。如果 Agent 会长期存在、被共享，或需要在应用启动时完成验证，应该显式调用 build。

构建错误包括空身份、零轮次限制、重复工具名、无效检索配置，以及工具与子 Agent 使用同一个可调用名称。

指令与上下文

使用 system 表达可信的应用策略，使用 context 提供模型可以引用和推理的证据。

let agent = runtime
    .agent("returns")
    .system("Never invent policy.")
    .context("Returns are accepted within 30 days.");

Runifold 会把上下文标记为不可信的用户级数据。检索到的文档永远不会变成系统指令，避免某段文本仅仅因为被 Retriever 选中就获得更高权限。

轮次与能力策略

max_turns 限制本地模型—工具循环。它与运行树共享的 Budget.turns 不同，后者会跨所有后代统一记账。

工具、推理或严格结构化输出等能力，可能在某个模型上不支持或处于未知状态。当应用必须失败关闭，而不能接受明确降级时，应配置 FeaturePolicy。

在 Tool 执行前审查计划

Runifold 0.9 可以在模型提出的 Tool Call 或子 Agent 委派获得权限前审查中间 Turn：

use runifold::{
    TerminalReviewVerdict, TurnReviewPolicy, TurnRuleReviewer,
};
 
let gate = TurnRuleReviewer::new("read-only-plan", "v1", |request| {
    if plan_is_read_only(&request.candidate) {
        Ok(TerminalReviewVerdict::approve())
    } else {
        TerminalReviewVerdict::repair(serde_json::json!({
            "code": "unsafe_plan",
            "instruction": "Choose a read-only evidence source."
        }))
    }
})?;
 
let agent = agent.turn_reviewer(
    gate,
    TurnReviewPolicy::new(2),
    reviewer_capabilities,
);

Repair 会丢弃尚未执行的计划，并在同一条有界 Transcript 中让原 Agent 重新考虑； Reject 直接失败关闭。默认只审查中间响应；只有确实需要同一 Gate 同时检查最终输出时，才使用 TurnReviewScope::EveryModelResponse。

Commit 前审查最终输出

通过 .terminal_reviewer(...) 挂载 AgentReviewer、确定性的 TerminalRuleReviewer 或组合 Reviewer。Completion 与结构化输出校验先执行，只有本地有效的 Candidate 才会进入语义审查。

use runifold::{AgentReviewer, ReviewRubric, TerminalReviewPolicy};
 
let reviewer = AgentReviewer::new(
    reviewer_agent,
    ReviewRubric::new(
        "evidence-correctness",
        "v1",
        "Approve only when every conclusion follows from stated evidence.",
    )?,
)?;
 
let agent = agent.terminal_reviewer(
    reviewer,
    TerminalReviewPolicy::new(2),
    reviewer_capabilities,
);

Reviewer 作为权限衰减的子 Run 执行，共享调用者的 Token、费用、Turn、Deadline 与取消预算。持久 Checkpoint 会绑定 Reviewer 名称、版本、策略、Capability 和 SHA-256 配置指纹。已准备好的 Candidate 恢复时不会重新生成；中断中的审查必须取得显式重试权限，避免静默重复审查。

生产检查清单：

为每个 Agent 指定稳定的名称与职责；
可信策略放入 system，证据放入 context；
设置有限的本地轮次；
在 Tool 执行前审查高风险计划，在 Commit 前审查关键答案；
只注册 Agent 真正需要的工具与子路由；
使用显式 RunContext 管理租户策略与共享记账。