Build and configure an Agent

The Agent shape

An Agent combines a model, trusted instructions, optional context, callable tools and child Agents, plus local execution policy. It does not own ambient credentials, a hidden memory backend, or an unbounded loop.

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

The Agent name is execution identity used in events and diagnostics. Choose a stable application name such as support, triage, or invoice-review, not a random request identifier.

Builder and validation

The fluent builder retains registration errors until build. This keeps tool and child-Agent registration chainable without silently replacing duplicate names.

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

prompt and prompt_text can build and run the builder directly for the ergonomic path. Call build yourself when the Agent is long-lived, shared, or validated during application startup.

Build failures include blank identity, zero turn limits, duplicate tool names, invalid retrieval configuration, and collisions between a tool and a child Agent.

Instructions vs context

Use system for trusted application policy. Use context for evidence the model may quote or reason over.

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

Runifold labels context as untrusted user-level data. Retrieved documents never become system instructions. This distinction prevents a document from gaining authority merely because it was selected by a retriever.

Turn and feature policy

max_turns bounds the local model-tool loop. It is separate from the shared run-tree Budget.turns, which accounts across descendants.

Provider features such as tools, reasoning, or strict structured output may be unsupported or unknown for a model. Configure FeaturePolicy when the application must fail closed instead of accepting an explicit degradation.

Review a plan before Tools execute

Runifold 0.9 can gate intermediate model turns before a proposed Tool call or child delegation receives authority:

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 discards the unexecuted plan and asks the original Agent to reconsider inside the same bounded transcript. Reject fails closed. The default scope is intermediate responses; use TurnReviewScope::EveryModelResponse only when the same gate should also inspect final output.

Review final output before commit

Attach an AgentReviewer, deterministic TerminalRuleReviewer, or composed reviewer through .terminal_reviewer(...). Completion and structured-output validation run first; only a locally valid candidate reaches semantic review.

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,
);

Reviewers execute as attenuated child Runs and share the caller's Token, cost, turn, deadline and cancellation budgets. Durable checkpoints bind reviewer name, version, policy, capabilities and a SHA-256 configuration fingerprint. A ready candidate resumes without regeneration; an interrupted in-flight review needs explicit retry authority, preventing silent duplicate review.

Production checklist:

• give every Agent a stable purpose and name;
• keep trusted policy in system, evidence in context;
• set a finite local turn limit;
• review risky plans before Tool execution and critical answers before commit;
• register only the tools and child routes the Agent needs;
• use an explicit RunContext for tenant policy and shared accounting.