Struct Agent 

pub struct Agent { /* private fields */ }

One configured model-tool agent.

Implementations

impl Agent

pub fn prompt<'a>( &'a self, input: impl Into<String> + Send + 'a, ) -> AgentFuture<'a, Result<AgentOutcome, AgentError>>

Runs a user text turn with a default root context.

This is the ergonomic surface for one-off prompts. It grants only callables registered on this Agent and applies no hard budget limit. Use Self::run when the caller must provide explicit authority, budget, deadline, observability, or run-tree identity.

pub fn prompt_text<'a>( &'a self, input: impl Into<String> + Send + 'a, ) -> AgentFuture<'a, Result<String, AgentError>>

Runs an ergonomic prompt and returns only model-visible text.

Rich content, usage, warnings, the canonical transcript, and provider events are intentionally discarded. Use Self::prompt when that information matters.

pub fn run<'a>( &'a self, input: impl Into<String> + Send + 'a, run: &'a RunContext, ) -> AgentFuture<'a, Result<AgentOutcome, AgentError>>

Runs a user text turn inside an existing runtime context.

pub fn run_conversation<'a>( &'a self, input: impl Into<String> + Send + 'a, run: &'a RunContext, store: &'a dyn ConversationStore, conversation_id: ConversationId, namespace: MemoryNamespace, policy: ConversationContextPolicy, ) -> AgentFuture<'a, Result<AgentConversationOutcome, AgentConversationError>>

Runs and atomically commits one bounded multi-turn conversation.

Transcript messages remain append-only. Execution-journal events stay in runifold_core::Journal, summaries remain lossy derived views, and semantic memory is injected only as explicitly untrusted context.

pub fn run_conversation_with_summary<'a>( &'a self, input: impl Into<String> + Send + 'a, run: &'a RunContext, store: &'a dyn ConversationStore, conversation_id: ConversationId, namespace: MemoryNamespace, automatic_summary: AutomaticConversationSummary<'a>, ) -> AgentFuture<'a, Result<AgentConversationOutcome, AgentConversationError>>

Summarizes an overflowing prefix before running a conversational turn.

Summary generation uses the supplied AutomaticConversationSummary and the same RunContext, preserving cancellation, deadline, budget, and journal behavior. The immutable transcript is never rewritten.

pub fn stream<'a>( &'a self, input: impl Into<String> + Send + 'a, run: &'a RunContext, ) -> AgentEventStream<'a>

Streams real-time events while driving the canonical Agent loop.

pub fn run_durable_conversation<'a>( &'a self, input: impl Into<String> + Send + 'a, run: &'a RunContext, store: Arc<dyn DurableConversationStore>, request: DurableConversationRequest, ) -> AgentFuture<'a, Result<AgentConversationOutcome, AgentConversationError>>

Runs one conversational turn with atomic transcript and checkpoint commit.

Intermediate checkpoints are written ahead of model and callable work. The terminal checkpoint and transcript append are committed together by DurableConversationStore.

pub fn resume_durable_conversation<'a>( &'a self, store: Arc<dyn DurableConversationStore>, checkpoint_id: CheckpointId, run: &'a RunContext, policy: ResumePolicy, ) -> AgentFuture<'a, Result<AgentConversationOutcome, AgentConversationError>>

Resumes a durable conversational turn from its write-ahead checkpoint.

pub fn run_checkpointed<'a>( &'a self, input: impl Into<String> + Send + 'a, run: &'a RunContext, checkpoint: &'a AgentCheckpoint, ) -> AgentFuture<'a, Result<AgentOutcome, AgentError>>

Runs with write-ahead checkpoint persistence.

pub fn resume<'a>( &'a self, checkpoint: &'a AgentCheckpoint, run: &'a RunContext, policy: ResumePolicy, ) -> AgentFuture<'a, Result<AgentOutcome, AgentError>>

Resumes a persisted Agent execution.

impl Agent

pub fn builder( name: impl Into<String>, model: Arc<dyn Model>, model_ref: ModelRef, ) -> AgentBuilder

Starts a fluent builder for an Agent.

pub fn new( name: impl Into<String>, model: Arc<dyn Model>, model_ref: ModelRef, ) -> Self

Creates an agent without instructions or tools.

pub fn system(self, instruction: impl Into<String>) -> Self

Appends a system instruction.

pub fn tools(self, tools: ToolRegistry) -> Self

Installs the registry whose tools are exposed and executable.

pub fn agents(self, agents: AgentGateway) -> Self

Installs the gateway whose child agents are exposed and callable.

pub fn effect_executor(self, effects: EffectExecutor) -> Self

Replaces the write-ahead effect coordinator shared by callables.

pub const fn effect_recovery_policy(self, policy: EffectRecoveryPolicy) -> Self

Sets recovery behavior for ambiguous callable effects.

pub const fn with_config(self, config: AgentConfig) -> Self

Replaces local execution configuration.

pub const fn min_successful_tool_calls(self, minimum: u32) -> Self

Requires this many successful local Tool calls before terminal output.

Failed Tool results, child-Agent delegations, provider-hosted Tools, and Tool results from earlier conversation turns do not satisfy this execution-local completion contract. A value of zero disables it.

pub fn output_format(self, output_format: OutputFormat) -> Self

Sets the desired format for the terminal model response.

pub fn structured_output<T>(self, name: impl Into<String>) -> Self

where T: JsonSchema,

Requests strict structured output described by the Rust type T.

pub fn into_structured<T>(self, name: impl Into<String>) -> StructuredAgent<T>

where T: JsonSchema,

Binds provider schema generation and local decoding to the same type.

pub fn name(&self) -> &str

Returns the stable local agent name.

pub const fn model_ref(&self) -> &ModelRef

Returns the provider and model identity used by this Agent.

pub fn callable_capabilities(&self) -> CapabilitySet

Returns capabilities for every Tool and child Agent exposed by this Agent.

The returned set is not granted automatically. Applications explicitly decide whether to install it on a root or delegated Run.

pub fn default_run_context(&self) -> RunContext

Creates a root context for the ergonomic prompt surface.

The context has no hard budget limits and grants only the Tool and child Agent capabilities explicitly registered on this Agent. Applications that need deadlines, tighter budgets, narrower authority, durable journals, or shared run trees should construct a RunContext and use Self::run instead.

Trait Implementations

impl Clone for Agent

fn clone(&self) -> Agent

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl ConversationSummarizer for Agent

fn summarize<'a>( &'a self, request: ConversationSummaryRequest, run: &'a RunContext, ) -> ConversationSummarizerFuture<'a, Result<String, ConversationSummarizerError>>

Rolls a previously committed summary forward over immutable entries.

impl Debug for Agent

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.