Skip to content

app

Application configuration definitions and loading utilities.

This module defines the top-level configuration model for the MADA multi-agent application. It provides AppConfig, which aggregates model, agent, database, MCP server, and interface configuration objects, along with load_config_from_json for loading a complete application configuration from a JSON file.

AppConfig dataclass

Top-level configuration for the MADA multi-agent application.

This configuration aggregates model settings, agent definitions, named MCP server definitions, database settings, orchestration settings, and optional interface layout settings. It can be loaded from a JSON file using the from_dict method.

Attributes:

Name Type Description
model ModelConfig

Provider-specific configuration for the model backend.
agents List[AgentConfig]

List of specialist agent definitions, including descriptions, optional named MCP server references, and legacy server_path entries.
database DatabaseConfig

Configuration for the database connection.
mcp_servers Dict[str, MCPServerConfig]

Named MCP server definitions.
interface InterfaceConfig

Configuration for the Gradio interface layout and options.
orchestration OrchestrationConfig

Mode and participant selection.
Source code in src/mada/core/config/app.py 
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
@dataclass
class AppConfig:
    """
    Top-level configuration for the MADA multi-agent application.

    This configuration aggregates model settings, agent definitions, named MCP
    server definitions, database settings, orchestration settings, and optional
    interface layout settings. It can be loaded from a JSON file using the
    `from_dict` method.

    Attributes:
        model (ModelConfig): Provider-specific configuration for the model backend.
        agents (List[AgentConfig]): List of specialist agent definitions,
            including descriptions, optional named MCP server references, and
            legacy `server_path` entries.
        database (DatabaseConfig): Configuration for the database connection.
        mcp_servers (Dict[str, MCPServerConfig]): Named MCP server definitions.
        interface (InterfaceConfig): Configuration for the Gradio interface layout and options.
        orchestration (OrchestrationConfig): Mode and participant selection.
    """

    model: ModelConfig
    agents: List[AgentConfig]
    database: DatabaseConfig
    mcp_servers: Dict[str, MCPServerConfig] = None  # MCP server configurations
    interface: InterfaceConfig = None  # Optional, used only by the Gradio app
    skills: SkillsConfig = field(default_factory=SkillsConfig)
    orchestration: OrchestrationConfig = field(default_factory=OrchestrationConfig)
    a2a: A2AConfig = field(default_factory=A2AConfig)
    a2a_agents: Dict[str, RemoteA2AAgentConfig] = field(default_factory=dict)
    telemetry: TelemetryConfig = field(default_factory=TelemetryConfig)

    @classmethod
    def from_dict(
        cls,
        config_dict: Dict[str, Any],
        config_dir: str | Path | None = None,
    ) -> "AppConfig":
        """
        Create an AppConfig instance from a dictionary.

        This method extracts and constructs the model, interface, and
        agent configurations from a flat configuration dictionary.

        Args:
            config_dict (Dict[str, Any]): Dictionary containing keys 'model', 'interface', and 'agents'.
            config_dir: Directory containing the configuration file. Relative
                skill paths and A2A card paths are resolved against it.
        Returns:
            AppConfig: The fully populated application configuration.

        Raises:
            ValueError: If the 'agents' list is missing or empty.
        """
        app_conf = {}

        # Load model configuration
        model_settings = config_dict.get("model")
        if not model_settings:
            raise ValueError(
                "Please provide 'model' settings in the configuration for your app."
            )
        model_cfg = load_model_config(model_settings)
        app_conf["model"] = model_cfg

        # Load agents
        agent_entries = config_dict.get("agents")
        if not agent_entries:
            raise ValueError(
                "No agents were provided. Please define at least one agent."
            )
        agent_cfgs = [AgentConfig.from_dict(agent) for agent in agent_entries]
        app_conf["agents"] = agent_cfgs

        # Load database
        database_config = config_dict.get("database", {})
        app_conf["database"] = load_database_config(database_config)

        orchestration_cfg = load_orchestration_config(config_dict.get("orchestration"))
        orchestration_cfg.validate_participants(
            [agent.agent_name for agent in agent_cfgs]
        )
        app_conf["orchestration"] = orchestration_cfg

        app_conf["telemetry"] = load_telemetry_config(config_dict.get("telemetry"))

        a2a_self_config, a2a_agents_config = _get_a2a_config_blocks(config_dict)
        app_conf["a2a"] = load_a2a_config(
            a2a_self_config,
            card_path_base=config_dir,
        )
        app_conf["a2a_agents"] = load_a2a_agents_config(a2a_agents_config)

        # Load MCP servers configuration (optional)
        python_exe = config_dict.get("python_executable", sys.executable)
        mcp_servers_entry = config_dict.get("mcp_servers")
        if mcp_servers_entry:
            mcp_servers_cfg = {}
            for name, server_config in mcp_servers_entry.items():
                if "python_executable" not in server_config:
                    server_config = {**server_config, "python_executable": python_exe}
                mcp_servers_cfg[name] = MCPServerConfig(**server_config)
            app_conf["mcp_servers"] = mcp_servers_cfg

        # Load skills configuration (optional)
        if "skill_paths" in config_dict or "skill_runtime" in config_dict:
            raise ValueError(
                "Use 'skills.skill_paths' and 'skills.skill_runtime' for skills configuration"
            )
        app_conf["skills"] = load_skills_config(
            config_dict.get("skills"), skill_path_base_dir=config_dir
        )

        # Load interface configuration (optional for multiagent app)
        interface_entry = config_dict.get("interface")
        if interface_entry:
            interface_cfg = InterfaceConfig(**config_dict["interface"])
            app_conf["interface"] = interface_cfg

        return cls(**app_conf)

from_dict(config_dict, config_dir=None) classmethod

Create an AppConfig instance from a dictionary.

This method extracts and constructs the model, interface, and agent configurations from a flat configuration dictionary.

Parameters:

Name Type Description Default
config_dict Dict[str, Any]

Dictionary containing keys 'model', 'interface', and 'agents'.

 required
config_dir str | Path | None

Directory containing the configuration file. Relative skill paths and A2A card paths are resolved against it.

 None

Returns: AppConfig: The fully populated application configuration.

Raises:

Type Description
ValueError

If the 'agents' list is missing or empty.
Source code in src/mada/core/config/app.py 
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
@classmethod
def from_dict(
    cls,
    config_dict: Dict[str, Any],
    config_dir: str | Path | None = None,
) -> "AppConfig":
    """
    Create an AppConfig instance from a dictionary.

    This method extracts and constructs the model, interface, and
    agent configurations from a flat configuration dictionary.

    Args:
        config_dict (Dict[str, Any]): Dictionary containing keys 'model', 'interface', and 'agents'.
        config_dir: Directory containing the configuration file. Relative
            skill paths and A2A card paths are resolved against it.
    Returns:
        AppConfig: The fully populated application configuration.

    Raises:
        ValueError: If the 'agents' list is missing or empty.
    """
    app_conf = {}

    # Load model configuration
    model_settings = config_dict.get("model")
    if not model_settings:
        raise ValueError(
            "Please provide 'model' settings in the configuration for your app."
        )
    model_cfg = load_model_config(model_settings)
    app_conf["model"] = model_cfg

    # Load agents
    agent_entries = config_dict.get("agents")
    if not agent_entries:
        raise ValueError(
            "No agents were provided. Please define at least one agent."
        )
    agent_cfgs = [AgentConfig.from_dict(agent) for agent in agent_entries]
    app_conf["agents"] = agent_cfgs

    # Load database
    database_config = config_dict.get("database", {})
    app_conf["database"] = load_database_config(database_config)

    orchestration_cfg = load_orchestration_config(config_dict.get("orchestration"))
    orchestration_cfg.validate_participants(
        [agent.agent_name for agent in agent_cfgs]
    )
    app_conf["orchestration"] = orchestration_cfg

    app_conf["telemetry"] = load_telemetry_config(config_dict.get("telemetry"))

    a2a_self_config, a2a_agents_config = _get_a2a_config_blocks(config_dict)
    app_conf["a2a"] = load_a2a_config(
        a2a_self_config,
        card_path_base=config_dir,
    )
    app_conf["a2a_agents"] = load_a2a_agents_config(a2a_agents_config)

    # Load MCP servers configuration (optional)
    python_exe = config_dict.get("python_executable", sys.executable)
    mcp_servers_entry = config_dict.get("mcp_servers")
    if mcp_servers_entry:
        mcp_servers_cfg = {}
        for name, server_config in mcp_servers_entry.items():
            if "python_executable" not in server_config:
                server_config = {**server_config, "python_executable": python_exe}
            mcp_servers_cfg[name] = MCPServerConfig(**server_config)
        app_conf["mcp_servers"] = mcp_servers_cfg

    # Load skills configuration (optional)
    if "skill_paths" in config_dict or "skill_runtime" in config_dict:
        raise ValueError(
            "Use 'skills.skill_paths' and 'skills.skill_runtime' for skills configuration"
        )
    app_conf["skills"] = load_skills_config(
        config_dict.get("skills"), skill_path_base_dir=config_dir
    )

    # Load interface configuration (optional for multiagent app)
    interface_entry = config_dict.get("interface")
    if interface_entry:
        interface_cfg = InterfaceConfig(**config_dict["interface"])
        app_conf["interface"] = interface_cfg

    return cls(**app_conf)

load_config_from_json(path)

Load application configuration from a JSON file.

Parameters:

Name Type Description Default
path str

Path to the JSON configuration file.

 required

Returns:

Name Type Description
AppConfig AppConfig

The parsed application configuration object.
Source code in src/mada/core/config/app.py 
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
def load_config_from_json(path: str) -> AppConfig:
    """
    Load application configuration from a JSON file.

    Args:
        path (str): Path to the JSON configuration file.

    Returns:
        AppConfig: The parsed application configuration object.
    """
    config_path = Path(path)
    with open(config_path, "r") as f:
        config_dict = json.load(f)

    config = AppConfig.from_dict(config_dict, config_dir=config_path.parent)

    return config