Struct AgentCore 

pub struct AgentCore { /* private fields */ }

AgentCore - Core runtime infrastructure for LLM-powered agents.

AgentCore provides all the infrastructure needed for an LLM-powered agent:

• Logging with tracing
• LLM configuration loading
• Tokio async runtime
• LLMController for session management
• Communication channels
• User interaction and permission registries

This is the runtime-only version. For TUI support, use the agent-core crate with the tui feature enabled, which provides the run() method.

Basic Usage (Headless)

use agent_core_runtime::agent::{AgentConfig, AgentCore};

struct MyConfig;
impl AgentConfig for MyConfig {
    fn config_path(&self) -> &str { ".myagent/config.yaml" }
    fn default_system_prompt(&self) -> &str { "You are helpful." }
    fn log_prefix(&self) -> &str { "myagent" }
    fn name(&self) -> &str { "MyAgent" }
}

fn main() -> std::io::Result<()> {
    let mut core = AgentCore::new(&MyConfig)?;
    core.start_background_tasks();

    // Get channels for custom frontend integration
    let tx = core.to_controller_tx();
    let rx = core.take_from_controller_rx();

    // Create a session and interact programmatically
    let (session_id, model, _) = core.create_initial_session()?;
    // ... send messages and receive responses via channels

    core.shutdown();
    Ok(())
}

Implementations

impl AgentCore

pub fn new<C>(config: &C) -> Result<AgentCore, Error>

where C: AgentConfig,

Create a new AgentCore with the given configuration.

This initializes:

• Logging infrastructure
• LLM configuration from config file or environment
• Tokio runtime
• Communication channels
• LLMController
• User interaction and permission registries

pub fn set_error_no_session( &mut self, message: impl Into<String>, ) -> &mut AgentCore

Set the error message shown when user submits but no session exists.

This overrides the default message “No active session. Use /new-session to create one.”

Example

agent.set_error_no_session("No configuration found in ~/.myagent/config.yaml");

pub fn error_no_session(&self) -> Option<&str>

Get the error message for no session, if set.

pub fn set_version(&mut self, version: impl Into<String>)

Set the agent version for display.

pub fn version(&self) -> &str

Get the agent version.

pub fn load_environment_context(&mut self) -> &mut AgentCore

Load environment context into the system prompt.

This adds information about the current execution environment to all LLM session prompts:

• Current working directory
• Platform (darwin, linux, windows)
• OS version
• Today’s date

The context is wrapped in <env> tags and appended to the system prompt.

Example

let mut core = AgentCore::new(&config)?;
core.load_environment_context();

pub fn register_tools<F>(&mut self, f: F) -> Result<(), AgentError>

where F: FnOnce(&Arc<ToolRegistry>, &Arc<UserInteractionRegistry>, &Arc<PermissionRegistry>) -> Result<Vec<Tool>, String>,

Register tools with the agent.

The callback receives references to the tool registry and interaction registries, and should return the tool definitions to register.

Example

core.register_tools(|registry, user_reg, perm_reg| {
    tools::register_all_tools(registry, user_reg, perm_reg)
})?;

pub fn register_tools_async<F, Fut>(&mut self, f: F) -> Result<(), AgentError>

where F: FnOnce(Arc<ToolRegistry>, Arc<UserInteractionRegistry>, Arc<PermissionRegistry>) -> Fut, Fut: Future<Output = Result<Vec<Tool>, String>>,

Register tools with the agent using an async function.

Similar to register_tools, but accepts an async closure. The closure is executed using the agent’s tokio runtime via block_on.

Example

core.register_tools_async(|registry, user_reg, perm_reg| async move {
    tools::register_all_tools(&registry, user_reg, perm_reg).await
})?;

pub fn start_background_tasks(&mut self)

Start the controller and input router as background tasks.

This must be called before sending messages or creating sessions. After calling this, the controller is running and ready to accept input.

pub fn create_initial_session( &mut self, ) -> Result<(i64, String, i32), AgentError>

Create an initial session using the default LLM provider.

Returns the session ID, model name, and context limit.

pub fn create_session( &self, config: LLMSessionConfig, ) -> Result<i64, AgentError>

Create a session with the given configuration.

Returns the session ID or an error.

pub fn shutdown(&self)

Signal shutdown to all background tasks and the controller.

pub fn to_controller_tx(&self) -> Sender<ControllerInputPayload>

Returns a sender for sending messages to the controller.

pub fn take_from_controller_rx(&mut self) -> Option<Receiver<UiMessage>>

Takes the receiver for messages from the controller (can only be called once).

pub fn controller(&self) -> &Arc<LLMController>

Returns a reference to the controller.

pub fn runtime(&self) -> &Runtime

Returns a reference to the runtime.

pub fn runtime_handle(&self) -> Handle

Returns a handle to the runtime.

pub fn user_interaction_registry(&self) -> &Arc<UserInteractionRegistry>

Returns a reference to the user interaction registry.

pub fn permission_registry(&self) -> &Arc<PermissionRegistry>

Returns a reference to the permission registry.

pub async fn remove_session(&self, session_id: i64) -> bool

Removes a session and cleans up all associated resources.

This is the recommended way to remove a session as it orchestrates cleanup across:

• The LLM session manager (terminates the session)
• The permission registry (cancels pending permission requests)
• The user interaction registry (cancels pending user questions)
• The tool registry (cleans up per-session state in tools)

Arguments

• session_id - The ID of the session to remove

Returns

true if the session was found and removed, false if session didn’t exist

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

Returns a reference to the LLM registry.

pub fn take_llm_registry(&mut self) -> Option<LLMRegistry>

Takes the LLM registry (can only be called once).

pub fn cancel_token(&self) -> CancellationToken

Returns the cancellation token.

pub fn name(&self) -> &str

Returns the agent name.

pub fn from_controller_tx(&self) -> Sender<UiMessage>

Returns a clone of the UI message sender.

This can be used to send messages to the frontend’s event loop.

pub fn tool_definitions(&self) -> &[Tool]

Returns a reference to the tool definitions.

Trait Implementations

impl AgentCoreExt for AgentCore

fn into_tui(self) -> TuiRunner

Convert this AgentCore into a TuiRunner for TUI operation.