Struct ModularAgent 

pub struct ModularAgent { /* private fields */ }

The central orchestrator for the modular agent system.

ModularAgent manages agent lifecycle, connections, and message routing. It maintains agent instances, connection maps, and handles ModularAgentEvents.

Lifecycle

1. init() - Create instance and register agent definitions
2. ready() - Start the internal message loop
3. Load presets with open_preset_from_file() or add_preset()
4. start_preset() - Start agents in a preset
5. Interact via write_external_input() and subscribe()
6. stop_preset() - Stop agents
7. quit() - Shut down

Example

use modular_agent_core::{ModularAgent, AgentValue, ModularAgentEvent};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize and start
    let ma = ModularAgent::init()?;
    ma.ready().await?;

    // Load a preset
    let preset_id = ma.open_preset_from_file("my_preset.json", None).await?;
    ma.start_preset(&preset_id).await?;

    // Send external input
    ma.write_external_input("input".to_string(), AgentValue::string("hello")).await?;

    // Cleanup
    ma.stop_preset(&preset_id).await?;
    ma.quit();
    Ok(())
}

Implementations

impl ModularAgent

pub fn new() -> Self

Create a new ModularAgent instance without registering agents.

For most use cases, prefer init() which also registers all agent definitions from the inventory.

pub fn init() -> Result<Self, AgentError>

Initialize a new ModularAgent instance.

This creates a new ModularAgent and registers all available agent definitions from the inventory. Call ready after this to start the message loop.

Example

use modular_agent_core::ModularAgent;

let ma = ModularAgent::init().unwrap();

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

Start the internal message loop.

This must be called after init before loading presets or sending messages. The message loop handles routing between agents and external output events.

Example

use modular_agent_core::ModularAgent;

#[tokio::main]
async fn main() {
    let ma = ModularAgent::init().unwrap();
    ma.ready().await.unwrap(); // Start the message loop
}

pub fn quit(&self)

Shut down the ModularAgent.

This stops the internal message loop. Call stop_preset for each running preset before calling this method for graceful shutdown.

Example

// Stop all presets first
ma.stop_preset(preset_id).await.unwrap();
// Then quit
ma.quit();

pub fn new_preset(&self) -> Result<String, AgentError>

Create a new empty preset.

Returns the id of the new preset. The preset is created with default settings and contains no agents or connections initially.

pub fn new_preset_with_name(&self, name: String) -> Result<String, AgentError>

Create a new empty preset with the given name.

Returns the id of the new preset.

pub fn get_preset(&self, id: &str) -> Option<Arc<AsyncMutex<Preset>>>

Get a preset by id.

Returns None if no preset exists with the given id.

pub fn add_preset(&self, spec: PresetSpec) -> Result<String, AgentError>

Add a new preset with the given spec, and returns the id of the new preset.

The ids of the given spec, including agents and connections, are changed to new unique ids. This allows the same spec to be added multiple times without id conflicts.

pub fn add_preset_with_name( &self, spec: PresetSpec, name: String, ) -> Result<String, AgentError>

Add a new preset with the given name and spec, and returns the id of the new preset.

The ids of the given spec, including agents and connections, are changed to new unique ids.

pub async fn rename_preset( &self, id: &str, new_name: String, ) -> Result<(), AgentError>

Rename a preset by id.

pub async fn remove_preset(&self, id: &str) -> Result<(), AgentError>

Remove a preset by id.

Stops the preset if running, then removes all associated agents and connections.

pub async fn start_preset(&self, id: &str) -> Result<(), AgentError>

Start a preset by id.

This starts all agents in the preset, enabling message flow between them. Each agent’s start() method is called.

pub async fn stop_preset(&self, id: &str) -> Result<(), AgentError>

Stop a preset by id.

This stops all agents in the preset, terminating message processing. Each agent’s stop() method is called.

pub async fn open_preset_from_file( &self, path: &str, name: Option<String>, ) -> Result<String, AgentError>

Open a preset from a JSON file.

Reads the file, parses the JSON as a PresetSpec, and adds it to the system. Optionally provide a custom name for the preset.

Arguments

• path - Path to the JSON preset file
• name - Optional custom name for the preset

pub async fn save_preset(&self, id: &str, path: &str) -> Result<(), AgentError>

Save a preset to a JSON file.

Serializes the current preset state (including agent configs) to JSON and writes it to the specified path.

pub async fn get_preset_spec(&self, id: &str) -> Option<PresetSpec>

Get the current preset spec by id.

pub async fn update_preset_spec( &self, id: &str, value: &Value, ) -> Result<(), AgentError>

Update the preset spec

pub async fn get_preset_info(&self, id: &str) -> Option<PresetInfo>

Get info of the preset by id.

pub async fn get_preset_infos(&self) -> Vec<PresetInfo>

Get infos of all presets.

pub fn register_agent_definiton(&self, def: AgentDefinition)

Register an agent definition.

This makes the agent type available for use in presets. The definition includes metadata (title, category), input/output ports, and config specs.

Note: Agents using #[modular_agent] macro are registered automatically via inventory.

pub fn get_agent_definitions(&self) -> AgentDefinitions

Get all registered agent definitions.

Returns a map of definition name to AgentDefinition.

pub fn get_agent_definition(&self, def_name: &str) -> Option<AgentDefinition>

Get an agent definition by name.

The name is typically in the format module::path::StructName.

pub fn get_agent_config_specs(&self, def_name: &str) -> Option<AgentConfigSpecs>

Get the config specs of an agent definition by name.

pub async fn get_agent_spec(&self, agent_id: &str) -> Option<AgentSpec>

Get the agent spec by id.

pub async fn update_agent_spec( &self, agent_id: &str, value: &Value, ) -> Result<(), AgentError>

Update the agent spec by id.

pub fn new_agent_spec(&self, def_name: &str) -> Result<AgentSpec, AgentError>

Create a new agent spec from the given agent definition name.

pub async fn add_agent( &self, preset_id: String, spec: AgentSpec, ) -> Result<String, AgentError>

Add an agent to the specified preset.

Creates a new agent instance from the given spec and adds it to the preset. Returns the id of the newly created agent. The agent is not started automatically; call start_preset or start_agent to start it.

pub fn get_agent( &self, agent_id: &str, ) -> Option<Arc<AsyncMutex<Box<dyn Agent>>>>

Get the agent by id.

pub async fn add_connection( &self, preset_id: &str, connection: ConnectionSpec, ) -> Result<(), AgentError>

Add a connection between two agents in the specified preset.

When the source agent outputs a value on the source handle (port), it will be delivered to the target agent’s target handle (port).

pub async fn add_agents_and_connections( &self, preset_id: &str, agents: &Vec<AgentSpec>, connections: &Vec<ConnectionSpec>, ) -> Result<(Vec<AgentSpec>, Vec<ConnectionSpec>), AgentError>

Add agents and connections to the specified preset.

The ids of the given agents and connections are changed to new unique ids. The agents are not started automatically, even if the preset is running.

pub async fn remove_agent( &self, preset_id: &str, agent_id: &str, ) -> Result<(), AgentError>

Remove an agent from the specified preset.

If the agent is running, it will be stopped first.

pub async fn remove_connection( &self, preset_id: &str, connection: &ConnectionSpec, ) -> Result<(), AgentError>

Remove a connection from the specified preset.

pub async fn start_agent(&self, agent_id: &str) -> Result<(), AgentError>

Start an agent by id.

Creates a message channel for the agent and spawns its event loop. The agent’s start() method is called, then the agent begins processing incoming messages.

If the agent’s definition has native_thread = true, the agent runs on a dedicated OS thread instead of the tokio runtime.

pub async fn stop_agent(&self, agent_id: &str) -> Result<(), AgentError>

Stop an agent by id.

Sends a stop message to the agent, closes its message channel, and calls the agent’s stop() method.

pub async fn set_agent_configs( &self, agent_id: String, configs: AgentConfigs, ) -> Result<(), AgentError>

Set configs for an agent by id.

pub fn get_global_configs(&self, def_name: &str) -> Option<AgentConfigs>

Get global configs for the agent definition by name.

pub fn set_global_configs(&self, def_name: String, configs: AgentConfigs)

Set global configs for the agent definition by name.

pub fn get_global_configs_map(&self) -> AgentConfigsMap

Get the global configs map.

pub fn set_global_configs_map(&self, new_configs_map: AgentConfigsMap)

Set the global configs map.

pub async fn send_agent_out( &self, agent_id: String, ctx: AgentContext, port: String, value: AgentValue, ) -> Result<(), AgentError>

Send output from an agent. (Async version)

pub fn try_send_agent_out( &self, agent_id: String, ctx: AgentContext, port: String, value: AgentValue, ) -> Result<(), AgentError>

Send output from an agent.

pub async fn write_external_input( &self, name: String, value: AgentValue, ) -> Result<(), AgentError>

Write a value to a named channel.

This is the primary method for sending external input into the agent network. The value will be delivered to all ExternalInputAgent instances listening to the specified channel name, which will then forward it to their connected agents.

Arguments

• name - The channel name to write to. Must match the name config of an ExternalInputAgent.
• value - The value to send.

Example

// Send a string to the "input" channel
ma.write_external_input("input".to_string(), AgentValue::string("hello")).await.unwrap();

// Send an integer
ma.write_external_input("numbers".to_string(), AgentValue::integer(42)).await.unwrap();

pub async fn write_local_input( &self, preset_id: &str, name: &str, value: AgentValue, ) -> Result<(), AgentError>

Write a value to the local variable channel.

pub fn subscribe(&self) -> Receiver<ModularAgentEvent>

Subscribe to all ModularAgent events.

Returns a broadcast receiver that receives all ModularAgentEvents. For filtered subscriptions, use subscribe_to_event.

Note: Subscribe before starting presets to avoid missing events.

pub fn subscribe_to_event<F, T>(&self, filter_map: F) -> UnboundedReceiver<T>

where F: FnMut(ModularAgentEvent) -> Option<T> + Send + 'static, T: Send + 'static,

Subscribe to filtered ModularAgentEvents.

This method creates a filtered subscription to events. The provided closure filters and maps events, and only successfully mapped events are forwarded to the returned receiver.

Important: Subscribe to events BEFORE starting presets to avoid missing events due to race conditions.

Arguments

• filter_map - A closure that receives each event and returns Some(T) for events you want to receive, or None to skip them.

Returns

An unbounded receiver that will receive the filtered and mapped events.

Example

use modular_agent_core::{ModularAgent, ModularAgentEvent, AgentValue};

// Subscribe to a specific channel's output
let output_channel = "output".to_string();
let mut output_rx = ma.subscribe_to_event(move |event| {
    if let ModularAgentEvent::ExternalOutput(name, value) = event {
        if name == output_channel {
            return Some(value);
        }
    }
    None
});

// Now start the preset and receive events
while let Some(value) = output_rx.recv().await {
    println!("Received: {:?}", value);
}

Trait Implementations

impl Clone for ModularAgent

fn clone(&self) -> ModularAgent

Returns a duplicate of the value.

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

Performs copy-assignment from source.