Struct AgentDefinition 

pub struct AgentDefinition {
    pub kind: String,
    pub name: String,
    pub title: Option<String>,
    pub hide_title: bool,
    pub description: Option<String>,
    pub category: Option<String>,
    pub inputs: Option<Vec<String>>,
    pub outputs: Option<Vec<String>>,
    pub configs: Option<AgentConfigSpecs>,
    pub global_configs: Option<FnvIndexMap<String, AgentConfigSpec>>,
    pub native_thread: bool,
    pub new_boxed: Option<fn(ma: ModularAgent, id: String, spec: AgentSpec) -> Result<Box<dyn Agent>, AgentError>>,
}

The definition (blueprint) of an agent type.

An agent definition describes the metadata and capabilities of an agent type, including its ports, configuration options, and factory function. Multiple agent instances can be created from a single definition.

Fields

kind: String

The kind/category identifier for this agent type (e.g., “Agent”, “Board”).

name: String

Unique name of this agent definition.

title: Option<String>

Human-readable title for display in UI.

hide_title: bool

Whether to hide the title in UI.

description: Option<String>

Description of what this agent does.

category: Option<String>

Category path for organizing agents (e.g., “Flow/Control”).

inputs: Option<Vec<String>>

Default input port names.

outputs: Option<Vec<String>>

Default output port names.

configs: Option<AgentConfigSpecs>

Configuration specifications for this agent type.

global_configs: Option<FnvIndexMap<String, AgentConfigSpec>>

Global configuration specifications (shared across instances).

native_thread: bool

Whether to run this agent on a native OS thread instead of the async runtime.

new_boxed: Option<fn(ma: ModularAgent, id: String, spec: AgentSpec) -> Result<Box<dyn Agent>, AgentError>>

Factory function to create new agent instances.

Implementations

impl AgentDefinition

pub fn new( kind: impl Into<String>, name: impl Into<String>, new_boxed: Option<fn(ma: ModularAgent, id: String, spec: AgentSpec) -> Result<Box<dyn Agent>, AgentError>>, ) -> Self

Creates a new agent definition.

Arguments

• kind - The kind/category identifier (e.g., “std”, “llm”)
• name - Unique name for this agent definition
• new_boxed - Optional factory function to create agent instances

pub fn title(self, title: &str) -> Self

Sets the display title. Returns self for method chaining.

pub fn hide_title(self) -> Self

Hides the title in UI. Returns self for method chaining.

pub fn description(self, description: &str) -> Self

Sets the description. Returns self for method chaining.

pub fn category(self, category: &str) -> Self

Sets the category path. Returns self for method chaining.

pub fn inputs(self, inputs: Vec<&str>) -> Self

Sets the input port names. Returns self for method chaining.

pub fn outputs(self, outputs: Vec<&str>) -> Self

Sets the output port names. Returns self for method chaining.

pub fn configs(self, configs: Vec<(&str, AgentConfigSpec)>) -> Self

Sets all configuration specifications at once.

pub fn unit_config(self, key: &str) -> Self

Adds a unit (trigger/signal) configuration.

pub fn unit_config_with<F>(self, key: &str, f: F) -> Self

where F: FnOnce(AgentConfigSpec) -> AgentConfigSpec,

Adds a unit configuration with customization callback.

pub fn boolean_config(self, key: &str, default: bool) -> Self

Adds a boolean configuration with a default value.

pub fn boolean_config_with<F>(self, key: &str, default: bool, f: F) -> Self

where F: FnOnce(AgentConfigSpec) -> AgentConfigSpec,

Adds a boolean configuration with customization callback.

pub fn boolean_config_default(self, key: &str) -> Self

Adds a boolean configuration with default value false.

pub fn integer_config(self, key: &str, default: i64) -> Self

Adds an integer configuration with a default value.

pub fn integer_config_with<F>(self, key: &str, default: i64, f: F) -> Self

where F: FnOnce(AgentConfigSpec) -> AgentConfigSpec,

Adds an integer configuration with customization callback.

pub fn integer_config_default(self, key: &str) -> Self

Adds an integer configuration with default value 0.

pub fn number_config(self, key: &str, default: f64) -> Self

Adds a number (f64) configuration with a default value.

pub fn number_config_with<F>(self, key: &str, default: f64, f: F) -> Self

where F: FnOnce(AgentConfigSpec) -> AgentConfigSpec,

Adds a number configuration with customization callback.

pub fn number_config_default(self, key: &str) -> Self

Adds a number configuration with default value 0.0.

pub fn string_config(self, key: &str, default: impl Into<String>) -> Self

Adds a string configuration with a default value.

pub fn string_config_with<F>( self, key: &str, default: impl Into<String>, f: F, ) -> Self

where F: FnOnce(AgentConfigSpec) -> AgentConfigSpec,

Adds a string configuration with customization callback.

pub fn string_config_default(self, key: &str) -> Self

Adds a string configuration with empty default value.

pub fn text_config(self, key: &str, default: impl Into<String>) -> Self

Adds a multiline text configuration with a default value.

pub fn text_config_with<F>( self, key: &str, default: impl Into<String>, f: F, ) -> Self

where F: FnOnce(AgentConfigSpec) -> AgentConfigSpec,

Adds a text configuration with customization callback.

pub fn text_config_default(self, key: &str) -> Self

Adds a text configuration with empty default value.

pub fn array_config(self, key: &str, default: impl Into<AgentValue>) -> Self

Adds an array configuration with a default value.

pub fn array_config_with<V: Into<AgentValue>, F>( self, key: &str, default: V, f: F, ) -> Self

where F: FnOnce(AgentConfigSpec) -> AgentConfigSpec,

Adds an array configuration with customization callback.

pub fn array_config_default(self, key: &str) -> Self

Adds an array configuration with empty default value.

pub fn object_config<V: Into<AgentValue>>(self, key: &str, default: V) -> Self

Adds an object configuration with a default value.

pub fn object_config_with<V: Into<AgentValue>, F>( self, key: &str, default: V, f: F, ) -> Self

where F: FnOnce(AgentConfigSpec) -> AgentConfigSpec,

Adds an object configuration with customization callback.

pub fn object_config_default(self, key: &str) -> Self

Adds an object configuration with empty default value.

pub fn custom_config_with<V: Into<AgentValue>, F>( self, key: &str, default: V, type_: &str, f: F, ) -> Self

where F: FnOnce(AgentConfigSpec) -> AgentConfigSpec,

Adds a custom-typed configuration with customization callback.

pub fn global_configs(self, configs: Vec<(&str, AgentConfigSpec)>) -> Self

Sets all global configuration specifications at once.

pub fn boolean_global_config(self, key: &str, default: bool) -> Self

Adds a boolean global configuration.

pub fn boolean_global_config_with<F>( self, key: &str, default: bool, f: F, ) -> Self

where F: FnOnce(AgentConfigSpec) -> AgentConfigSpec,

Adds a boolean global configuration with customization callback.

pub fn integer_global_config(self, key: &str, default: i64) -> Self

Adds an integer global configuration.

pub fn integer_global_config_with<F>( self, key: &str, default: i64, f: F, ) -> Self

where F: FnOnce(AgentConfigSpec) -> AgentConfigSpec,

Adds an integer global configuration with customization callback.

pub fn number_global_config(self, key: &str, default: f64) -> Self

Adds a number (f64) global configuration.

pub fn number_global_config_with<F>(self, key: &str, default: f64, f: F) -> Self

where F: FnOnce(AgentConfigSpec) -> AgentConfigSpec,

Adds a number global configuration with customization callback.

pub fn string_global_config(self, key: &str, default: impl Into<String>) -> Self

Adds a string global configuration.

pub fn string_global_config_with<F>( self, key: &str, default: impl Into<String>, f: F, ) -> Self

where F: FnOnce(AgentConfigSpec) -> AgentConfigSpec,

Adds a string global configuration with customization callback.

pub fn text_global_config(self, key: &str, default: impl Into<String>) -> Self

Adds a multiline text global configuration.

pub fn text_global_config_with<F>( self, key: &str, default: impl Into<String>, f: F, ) -> Self

where F: FnOnce(AgentConfigSpec) -> AgentConfigSpec,

Adds a text global configuration with customization callback.

pub fn array_global_config( self, key: &str, default: impl Into<AgentValue>, ) -> Self

Adds an array global configuration.

pub fn array_global_config_with<V: Into<AgentValue>, F>( self, key: &str, default: V, f: F, ) -> Self

where F: FnOnce(AgentConfigSpec) -> AgentConfigSpec,

Adds an array global configuration with customization callback.

pub fn array_global_config_default(self, key: &str) -> Self

Adds an array global configuration with empty default value.

pub fn object_global_config<V: Into<AgentValue>>( self, key: &str, default: V, ) -> Self

Adds an object global configuration.

pub fn object_global_config_with<V: Into<AgentValue>, F>( self, key: &str, default: V, f: F, ) -> Self

where F: FnOnce(AgentConfigSpec) -> AgentConfigSpec,

Adds an object global configuration with customization callback.

pub fn custom_global_config_with<V: Into<AgentValue>, F>( self, key: &str, default: V, type_: &str, f: F, ) -> Self

where F: FnOnce(AgentConfigSpec) -> AgentConfigSpec,

Adds a custom-typed global configuration with customization callback.

pub fn use_native_thread(self) -> Self

Configures this agent to run on a native OS thread.

Use this for agents that perform blocking I/O or CPU-intensive operations that would block the async runtime.

pub fn to_spec(&self) -> AgentSpec

Creates a new agent specification from this definition.

Generates a unique ID and copies the definition’s ports and configs to create a new instance specification.

pub fn reconcile_spec(&self, spec: &mut AgentSpec)

Reconciles an existing AgentSpec with this definition for backward compatibility.

When loading old JSON presets, the spec may not match the current definition. This method:

• Fills missing config keys with definition defaults
• Renames stale keys (not in definition) with _ prefix for lazy migration
• Overwrites config_specs with current definition metadata
• Overwrites ports with current definition ports

Keys already starting with _ are skipped during rename (idempotency). _-prefixed keys are cleaned up by AgentData::new().

Config names must not start with _ (reserved for stale key migration).

Trait Implementations

impl Clone for AgentDefinition

fn clone(&self) -> AgentDefinition

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AgentDefinition

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

Formats the value using the given formatter.

impl Default for AgentDefinition

fn default() -> AgentDefinition

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for AgentDefinition

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for AgentDefinition

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.