1  ---
 2  title: Project Structure
 3  sidebar_position: 410
 4  ---
 5  
 6  # Project Structure
 7  
 8  Agent Mesh is built on the A2A (Agent-to-Agent) protocol architecture, powered by [Solace AI Connector](https://github.com/SolaceLabs/solace-ai-connector), and uses the Solace event broker as the communication backbone. The framework is controlled by YAML configuration files that define agents, gateways, and plugins, enabling distributed AI agent communication through event-driven messaging.
 9  
10  A fresh Agent Mesh project follows this structure:
11  
12  ```
13  my-sam-project/
14  ├── configs/
15  │   ├── shared_config.yaml           # Shared broker, models, and services config
16  │   ├── agents/
17  │   │   └── main_orchestrator.yaml   # Default orchestrator agent
18  │   └── gateways/
19  │   │   └── webui.yaml              # Default web UI gateway
20  │   ├── plugins/
21  ├── src/                            # Custom Python components (optional)
22  │   └── __init__.py
23  ```
24  
25  The `configs/` directory uses a logical organization:
26  
27  - the `agents/` directory contains agent configuration files
28  - the `gateways/` directory contains gateway configuration files
29  - the `plugins/` directory contains plugin configuration files (created when plugins are added)
30  
31  Further subdirectories can be created within `agents/`, `gateways/`, and `plugins/` to organize configurations by functionality or purpose. 
32  
33  
34  :::info[File Discovery]
35  The CLI automatically crawls through the `configs` directory to find configuration files. Files that start with `_` (underscore) or `shared_config` are ignored and not processed by the CLI. For example:
36  - `_example_agent.yaml` is ignored
37  - `shared_config_for_db_agents.yaml` is ignored (Can still be included in other config files using `!include` directive)
38  :::
39  
40  ### Shared Configuration
41  
42  The `shared_config.yaml` file is the foundation of your project configuration. It contains common elements that are reused across all agents and gateways using YAML anchors:
43  
44  - **Broker Connection**: Solace event broker settings for A2A communication
45  - **Model Definitions**: LLM model configurations (planning, general, multimodal, etc.)
46  - **Services**: Artifact service, session service, and data tools configuration
47  
48  This shared configuration approach eliminates duplication and ensures consistency across your entire project. Each agent and gateway configuration file references these shared elements using YAML anchor syntax (`*reference_name`).
49  
50  Further values can be added to the shared configuration file as needed, and they are available to all agents and gateways that include it.
51  
52  ## YAML Configuration Files
53  
54  Each configuration file defines one (recommended) or more applications that can be run independently. The framework supports:
55  
56  - **Agent Applications**: A2A-enabled agents that use Google ADK runtime and Agent Mesh framework
57  - **Gateway Applications**: Protocol translators that bridge external interfaces to adopted A2A protocol
58  - **Plugin Applications**: Specialized components that extend framework capabilities
59  
60  ## Configuration Management
61  
62  - **Environment Variables**: Configuration values use environment variables for flexibility across environments
63  - **Shared Configuration**: Common settings are defined once in `shared_config.yaml` and referenced using YAML anchors (`&` and `*`)
64  - **Automatic Generation**: The `sam add agent`, `sam add gateway`, and `sam plugin add` commands automatically generate appropriate configuration files
65  - **Standalone Execution**: Each configuration file can be run independently using `sam run <config-file>`
66  
67  ## Python Components
68  
69  Although most functionality is configured through YAML, custom Python components can be added to the `src/` directory when needed. The framework provides base classes for extending functionality such as custom agent tools, gateway protocol handlers, and service providers.