Struct RuntimeAgent 

pub struct RuntimeAgent { /* private fields */ }

Implementations

impl RuntimeAgent

pub fn new( info: AgentInfo, llm_registry: Arc<LLMRegistry>, memory: Arc<dyn Memory>, tools: Arc<ToolRegistry>, skills: Vec<SkillDefinition>, system_prompt: String, max_iterations: u32, ) -> Self

Constructs a runtime with one gate shared by every external root-turn entry point.

pub fn with_declared_tool_ids(self, ids: Option<Vec<String>>) -> Self

pub fn with_storage_config(self, config: StorageConfig) -> Self

pub fn with_storage(self, storage: Arc<dyn AgentStorage>) -> Self

pub fn with_reasoning(self, config: ReasoningConfig) -> Self

pub fn with_reflection(self, config: ReflectionConfig) -> Self

pub fn with_relationships(self, manager: Arc<RelationshipManager>) -> Self

Attach a relationship manager configured by the builder or host application.

pub fn with_observability(self, manager: Arc<ObservabilityManager>) -> Self

Attach a shared observability manager for traces, metrics, reports, and exports.

pub fn with_runtime_config(self, config: RuntimeConfig) -> Self

Attach runtime optimization policy and resize the background queue.

pub fn runtime_config(&self) -> &RuntimeConfig

Returns the runtime optimization policy.

pub async fn flush_background_tasks(&self) -> Result<()>

Wait for all background maintenance tasks to finish.

pub async fn flush_background_tasks_for_actor( &self, actor_id: &str, ) -> Result<()>

Wait for background maintenance associated with one actor to finish.

pub async fn flush_background_tasks_for_purpose( &self, purpose: RuntimeTaskPurpose, ) -> Result<()>

Wait for background maintenance associated with one task kind to finish.

pub async fn flush_background_tasks_for_actor_purpose( &self, actor_id: &str, purpose: RuntimeTaskPurpose, ) -> Result<()>

Wait for background maintenance associated with one actor and task kind to finish.

pub async fn shutdown_background_tasks(&self) -> Result<()>

Flush background maintenance before a host shuts down the runtime.

pub fn observability(&self) -> Option<Arc<ObservabilityManager>>

Returns the configured observability manager for report and export access.

pub fn relationship_manager(&self) -> Option<Arc<RelationshipManager>>

Returns the configured relationship manager, if relationship memory is enabled.

pub async fn chat_with_actor_context( &self, input: &str, actor_context: TurnActorContext, ) -> Result<AgentResponse>

Run one serialized turn with turn-scoped actor context without mutating the runtime’s global actor ID.

The supplied context is available to actor-scoped facts, relationship memory, orchestration, and prompt templates only for the lifetime of this call.

pub async fn chat_as_actor( &self, actor_id: &str, input: &str, ) -> Result<AgentResponse>

Convenience wrapper around Self::chat_with_actor_context for a turn whose original actor is known up front.

pub async fn load_actor_relationship(&self) -> Result<()>

Ensure the effective actor’s relationship is loaded from storage into the relationship manager.

pub async fn update_relationship_dimension( &self, dimension: &str, delta: f64, reason: Option<&str>, ) -> Result<DimensionChange>

Manually apply a delta to the effective actor’s agent_to_actor relationship perspective and persist the updated relationship when storage is configured.

pub async fn update_relationship_dimension_for_perspective( &self, perspective: RelationshipPerspective, dimension: &str, delta: f64, reason: Option<&str>, ) -> Result<DimensionChange>

Manually apply a delta to a specific relationship perspective for the effective actor.

Use this for two-sided configurations when you need to update agent_to_actor, perceived_actor_to_agent, or mutual explicitly from application logic.

pub fn reasoning_config(&self) -> &ReasoningConfig

pub fn reflection_config(&self) -> &ReflectionConfig

pub fn with_facts_config( self, actor_memory_config: Option<ActorMemoryConfig>, facts_config: Option<FactsConfig>, ) -> Self

Set only the actor memory and facts configs without creating the store. The store and extractor are created lazily in init_storage().

pub fn with_facts( self, store: Arc<FactStore>, extractor: Option<Arc<dyn FactExtractor>>, actor_memory_config: Option<ActorMemoryConfig>, facts_config: Option<FactsConfig>, ) -> Self

Configure fact store and optional extractor for actor memory. Pass None for extractor to load existing facts without running extraction.

pub fn fact_store(&self) -> Option<Arc<FactStore>>

Get the fact store for direct fact manipulation.

pub fn actor_id(&self) -> Option<String>

Get the current actor ID.

pub fn set_actor_id(&self, actor_id: &str) -> Result<()>

Set the current actor ID (player, user, another agent, etc.).

pub fn clear_actor_id(&self)

Clear the current actor binding while retaining the session actor roster.

pub fn set_user_id(&self, user_id: &str) -> Result<()>

Set the current actor ID. Convenience wrapper around set_actor_id.

pub async fn load_actor_memory(&self) -> Result<()>

Load facts for the current actor from storage and cache them for prompt injection.

pub fn actor_facts(&self) -> Vec<KeyFact>

Get cached actor facts for the effective actor.

pub fn relationship_memory_text(&self) -> Option<String>

Returns the formatted relationship prompt text for the effective actor, if relationship injection produced any text for this turn.

pub async fn extract_facts(&self, last_n: usize) -> Result<Vec<KeyFact>>

Manually extract facts from the last N messages.

pub fn with_persona(self, manager: Arc<PersonaManager>) -> Self

pub fn persona_manager(&self) -> Option<&Arc<PersonaManager>>

pub fn with_disambiguation(self, config: DisambiguationConfig) -> Self

pub fn disambiguation_manager(&self) -> Option<&DisambiguationManager>

pub fn has_disambiguation(&self) -> bool

pub async fn init_storage(&self) -> Result<()>

pub fn storage(&self) -> Option<Arc<dyn AgentStorage>>

pub fn storage_config(&self) -> &StorageConfig

pub fn spawner(&self) -> Option<&Arc<AgentSpawner>>

Returns the spawner if configured via a spawner: YAML section.

pub fn spawner_registry(&self) -> Option<&Arc<AgentRegistry>>

Returns the agent registry if configured via a spawner: YAML section.

pub fn has_spawner(&self) -> bool

pub fn with_spawner_handles( self, spawner: Arc<AgentSpawner>, registry: Arc<AgentRegistry>, ) -> Self

pub fn with_hooks(self, hooks: Arc<dyn AgentHooks>) -> Self

pub fn with_parallel_tools(self, config: ParallelToolsConfig) -> Self

pub fn with_streaming(self, config: StreamingConfig) -> Self

pub fn with_hitl( self, engine: HITLEngine, handler: Arc<dyn ApprovalHandler>, ) -> Self

pub fn with_max_context_tokens(self, tokens: u32) -> Self

pub fn with_memory_token_budget(self, budget: MemoryTokenBudget) -> Self

pub fn with_recovery_manager(self, manager: RecoveryManager) -> Self

pub fn with_tool_security(self, engine: ToolSecurityEngine) -> Self

pub fn runtime_control(&self) -> RuntimeControlHandle

Returns the host-only runtime control handle.

pub fn set_question_handler(&self, handler: Option<Arc<dyn QuestionHandler>>)

Installs or clears the host question handler used by ask_user.

pub fn set_diagnostics_provider(&self, provider: Arc<dyn DiagnosticsProvider>)

Installs the host diagnostics provider used by diagnostics.

pub fn set_command_runner(&self, runner: Arc<dyn CommandRunner>)

Installs the host command runner used by command.

pub fn set_web_search_provider(&self, provider: Arc<dyn WebSearchProvider>)

Installs the host web-search provider used by web_search.

pub fn todos(&self) -> Vec<TodoItem>

Returns the current session-local todo list.

pub fn with_process_processor(self, processor: ProcessProcessor) -> Self

pub fn with_state_machine( self, state_machine: Arc<StateMachine>, evaluator: Arc<dyn TransitionEvaluator>, ) -> Self

pub fn with_context_manager(self, manager: Arc<ContextManager>) -> Self

pub fn register_message_filter( &self, name: impl Into<String>, filter: Arc<dyn MessageFilter>, )

pub fn set_context(&self, key: &str, value: Value) -> Result<()>

pub fn update_context(&self, path: &str, value: Value) -> Result<()>

pub fn get_context(&self) -> HashMap<String, Value>

pub fn remove_context(&self, key: &str) -> Option<Value>

pub async fn refresh_context(&self, key: &str) -> Result<()>

pub fn register_context_provider( &self, name: &str, provider: Arc<dyn ContextProvider>, )

pub fn current_state(&self) -> Option<String>

pub async fn transition_to(&self, state: &str) -> Result<()>

Applies a manual transition after reserving its exit actions and keeping async lifecycle work outside the commit lock.

pub fn state_history(&self) -> Vec<StateTransitionEvent>

pub fn session_metadata(&self) -> SessionMetadata

Get a copy of current session metadata.

pub async fn delete_actor_data(&self, actor_id: &str) -> Result<()>

Delete all facts and sessions for an actor, gated by privacy.allow_deletion. Returns Err when actor_memory.privacy.allow_deletion is false.

pub fn set_session_metadata(&self, meta: SessionMetadata)

Overwrite session metadata (tags, ttl, custom fields).

pub async fn cleanup_expired_sessions(&self) -> Result<usize>

Delete sessions whose TTL has expired. Returns number of sessions removed.

pub async fn list_sessions_filtered( &self, filter: &SessionFilter, ) -> Result<Vec<SessionSummary>>

List sessions matching a filter. Supports actor, tag, and date filters.

pub async fn save_state(&self) -> Result<AgentSnapshot>

pub async fn save_state_full(&self) -> Result<AgentSnapshot>

Save state including spawned agents manifest for session persistence.

pub async fn restore_state(&self, snapshot: AgentSnapshot) -> Result<()>

Restores persisted state after invalidating any pending confirmation ownership.

pub async fn save_to( &self, storage: &dyn AgentStorage, session_id: &str, ) -> Result<()>

pub async fn load_from( &self, storage: &dyn AgentStorage, session_id: &str, ) -> Result<bool>

pub async fn save_session(&self, session_id: &str) -> Result<()>

pub async fn load_session(&self, session_id: &str) -> Result<bool>

pub async fn restore_session_full(&self, session_id: &str) -> Result<usize>

Restore this runtime and its complete saved child topology from one named session.

pub async fn delete_session(&self, session_id: &str) -> Result<()>

pub async fn list_sessions(&self) -> Result<Vec<String>>

pub fn info(&self) -> AgentInfo

pub fn skills(&self) -> &[SkillDefinition]

pub async fn reset(&self) -> Result<()>

Resets the runtime using the same cleanup path as the Agent trait.

pub fn max_context_tokens(&self) -> u32

pub fn llm_registry(&self) -> &Arc<LLMRegistry>

pub fn state_machine(&self) -> Option<&Arc<StateMachine>>

pub fn context_manager(&self) -> &Arc<ContextManager>

pub fn tool_call_history(&self) -> Vec<ToolCallRecord>

pub fn memory_token_budget(&self) -> Option<&MemoryTokenBudget>

pub fn parallel_tools_config(&self) -> &ParallelToolsConfig

pub fn streaming_config(&self) -> &StreamingConfig

pub fn hooks(&self) -> &Arc<dyn AgentHooks>

pub fn hitl_engine(&self) -> Option<&HITLEngine>

pub fn approval_handler(&self) -> &Arc<dyn ApprovalHandler>

pub async fn check_state_hitl( &self, from: Option<&str>, to: &str, ) -> Result<bool>

pub async fn chat_stream<'a>( &'a self, input: &'a str, ) -> Result<Pin<Box<dyn Stream<Item = StreamChunk> + Send + 'a>>>

Streams one serialized root turn and releases its owned gate guard at Done or when the stream is dropped.

The captured immutable identity stack is restored for every inner poll and export with an Arc clone, so nested hooks and orchestration calls detect same-runtime reentry without rebuilding ancestry. The inner stream is drained after Done before ownership is released.

pub async fn chat_stream_events<'a>( &'a self, input: &'a str, ) -> Result<Pin<Box<dyn Stream<Item = AgentStreamEvent> + Send + 'a>>>

Streams one serialized root turn and releases its owned gate guard at the authoritative terminal event or on drop.

The captured immutable identity stack is restored for every inner poll and export with an Arc clone. The event API shares and drains the legacy execution stream so cleanup, nested-call detection, cancellation, and side effects cannot diverge before the gate is released.

Trait Implementations

impl Agent for RuntimeAgent

fn chat<'life0, 'life1, 'async_trait>( &'life0 self, input: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<AgentResponse>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Runs one blocking external root turn with task-local ownership visible through finalization, hooks, orchestration, and export.

fn reset<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Resets the runtime without leaving clarification or skill ownership behind.

fn info(&self) -> AgentInfo

impl Debug for RuntimeAgent

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

Formats the value using the given formatter.

impl ToolInvoker for RuntimeAgent

fn invoke_tool<'life0, 'async_trait>( &'life0 self, request: ToolExecutionRequest, ) -> Pin<Box<dyn Future<Output = Result<ToolExecutionRecord>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Invokes a tool request and returns a structured execution record.