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

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

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

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

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

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

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

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

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

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

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

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<(), AgentError>

Wait for all background maintenance tasks to finish.

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

Wait for background maintenance associated with one actor to finish.

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

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<(), AgentError>

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

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

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, AgentError>

Run one 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, AgentError>

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<(), AgentError>

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, AgentError>

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, AgentError>

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

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

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<(), AgentError>

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

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

Set the current actor ID. Convenience wrapper around set_actor_id.

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

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>, AgentError>

Manually extract facts from the last N messages.

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

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

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

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

pub fn has_disambiguation(&self) -> bool

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

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

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

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

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

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

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

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

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

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

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 todos(&self) -> Vec<TodoItem>

Returns the current session-local todo list.

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

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

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

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

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

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

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<(), AgentError>

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<(), AgentError>

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<(), AgentError>

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, AgentError>

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

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

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

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

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

Save state including spawned agents manifest for session persistence.

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

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

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

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

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

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

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

pub fn info(&self) -> AgentInfo

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

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

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, AgentError>

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

Stream a chat response with real-time updates

Trait Implementations

impl Agent for RuntimeAgent

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

where 'life0: 'async_trait, 'life1: 'async_trait, RuntimeAgent: 'async_trait,

fn info(&self) -> AgentInfo

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

where 'life0: 'async_trait, RuntimeAgent: 'async_trait,

impl Debug for RuntimeAgent

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

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, AgentError>> + Send + 'async_trait>>

where 'life0: 'async_trait, RuntimeAgent: 'async_trait,

Invokes a tool request and returns a structured execution record.