Skip to main content

Configuring Agent Mesh

The shared_config.yaml file is used to define configurations that can be shared across multiple agents or components in Agent Mesh. This centralized approach simplifies management of common configurations such as Solace event broker connections, language model settings, and service definitions.

Understanding Shared Configuration​

All agents and gateways require access to a shared_config object. You can provide configuration in the following ways:

  • hard-coding configuration values directly within your agent or gateway YAML files. This method works for simple setups or quick prototyping, but it becomes unwieldy as your deployment grows.
  • using the !include directive to reference a centralized configuration file. This approach promotes consistency and simplifies maintenance across your entire project.

When a plugin is installed, it may come with hard-coded default values. It is a best practice to remove this section and use !include to point to the centralized shared_config file. This ensures that all components are using the same base configuration.

Managing Multiple Shared Configuration Files​

You can use multiple shared configuration files to manage different environments or setups (e.g., for different cloud providers), as follows:

  • The filename must always begin with shared_config, followed by any descriptive suffix that helps identify the configuration's purpose. Examples include shared_config_aws.yaml for Amazon Web Services deployments or shared_config_production.yaml for production environments. This naming convention ensures the system can locate and process these files correctly.

  • You can organize configuration files into subdirectories to further improve project structure. For instance, you might place files in configs/agents/shared_config.yaml or environments/dev/shared_config_dev.yaml. When you use subdirectories, you must update the !include path in your agent or gateway configurations to reflect the correct file location.

The configuration file uses YAML anchors (&anchor_name) to create reusable configuration blocks, which can then be referenced in agent configuration files.

Configuration Structure​

The following example shows the structure of the shared_config.yaml configuration file:

shared_config:
  - broker_connection: &broker_connection
      dev_mode: ${SOLACE_DEV_MODE, false}
      broker_url: ${SOLACE_BROKER_URL, ws://localhost:8008}
      broker_username: ${SOLACE_BROKER_USERNAME, default}
      broker_password: ${SOLACE_BROKER_PASSWORD, default}
      broker_vpn: ${SOLACE_BROKER_VPN, default}
      temporary_queue: ${USE_TEMPORARY_QUEUES, true}
      # Ensure high enough limits if many agents are running
      # max_connection_retries: -1 # Retry forever

  - models:
    planning: &planning_model
      # This dictionary structure tells ADK to use the LiteLlm wrapper.
      # 'model' uses the specific model identifier your endpoint expects.
      model: ${LLM_SERVICE_PLANNING_MODEL_NAME} # Use env var for model name
      # 'api_base' tells LiteLLM where to send the request.
      api_base: ${LLM_SERVICE_ENDPOINT} # Use env var for endpoint URL
      # 'api_key' provides authentication.
      api_key: ${LLM_SERVICE_API_KEY} # Use env var for API key
      # Enable parallel tool calls for planning model
      parallel_tool_calls: true
      # Prompt Caching Strategy
      cache_strategy: "5m" # none, 5m, 1h
      # max_tokens: ${MAX_TOKENS, 16000} # Set a reasonable max token limit for planning
      # temperature: 0.1 # Lower temperature for more deterministic planning
    
    general: &general_model
      # This dictionary structure tells ADK to use the LiteLlm wrapper.
      # 'model' uses the specific model identifier your endpoint expects.
      model: ${LLM_SERVICE_GENERAL_MODEL_NAME} # Use env var for model name
      # 'api_base' tells LiteLLM where to send the request.
      api_base: ${LLM_SERVICE_ENDPOINT} # Use env var for endpoint URL
      # 'api_key' provides authentication.
      api_key: ${LLM_SERVICE_API_KEY} # Use env var for API key

      # ... (similar structure)

  - services:
    # Default session service configuration
    session_service: &default_session_service
      type: "memory"
      default_behavior: "PERSISTENT"
    
    # Default artifact service configuration
    artifact_service: &default_artifact_service
      type: "filesystem"
      base_path: "/tmp/samv2"
      artifact_scope: namespace
    
    # Default data tools configuration
    data_tools_config: &default_data_tools_config
      sqlite_memory_threshold_mb: 100
      max_result_preview_rows: 50
      max_result_preview_bytes: 4096

Event Broker Connection​

The broker_connection section configures the connection to the Solace event broker. The connection parameters are described in the following table:

ParameterEnvironment VariableDescriptionDefault
dev_modeSOLACE_DEV_MODEWhen set to true, uses an in-memory broker for testing.false
broker_urlSOLACE_BROKER_URLThe URL of the Solace event broker.ws://localhost:8008
broker_usernameSOLACE_BROKER_USERNAMEThe username for authenticating with the event broker.default
broker_passwordSOLACE_BROKER_PASSWORDThe password for authenticating with the event broker.default
broker_vpnSOLACE_BROKER_VPNThe Message VPN to connect to on the event broker.default
temporary_queueUSE_TEMPORARY_QUEUESWhether to use temporary queues for communication. If false, a durable queue will be created.true
max_connection_retriesMAX_CONNECTION_RETRIESThe maximum number of times to retry connecting to the event broker if the connection fails. A value of -1 means retry forever.-1
tip

If you need to configure multiple brokers, you can do so by adding additional entries under shared_config with a unique name (For example, broker_connection_eu: &broker_connection_eu or broker_connection_us: &broker_connection_us). Reference these configurations in your agent files using the appropriate anchor, such as <<: *broker_connection_eu.

info

Setting the temporary_queue parameter to true (default) will use temporary endpoints for A2A communication. Temporary queues are automatically created and deleted by the broker, which simplifies management and reduces the need for manual cleanup. However, it does not allow for multiple client connections to the same queue, which may be a limitation in some scenarios where you're running multiple instances of the same agent or a new instance needs to be started while an old instance is still running.

If you set temporary_queue to false, the system will create a durable queue for the client. Durable queues persist beyond the lifetime of the client connection, allowing multiple clients to connect to the same queue and ensuring that messages are not lost if the client disconnects. However, this requires manual management of the queues, including cleanup of unused queues.

Check the Setting up Queue Templates section for guidance on configuring queue templates to manage message TTL.

LLM Configuration​

The models section configures the various Large Language Models and other generative models that power your agents' intelligence. This configuration leverages the LiteLLM library, which provides a standardized interface for interacting with different model providers, simplifying the process of switching between or combining multiple AI services.

Model Configuration Parameters​

Each model configuration requires specific parameters that tell the system how to communicate with the model provider. The model parameter specifies the exact model identifier in the format expected by your provider, such as openai/gpt-4 or anthropic/claude-3-opus-20240229. The API base URL points to your provider's endpoint, but some providers use default endpoints that don't require explicit specification.

Authentication typically requires an API key, but some providers use alternative authentication mechanisms. Additional parameters control model behavior, such as enabling parallel tool calls for models that support this feature, setting maximum token limits to control response length and costs, and adjusting temperature values to influence response creativity versus determinism.

ParameterEnvironment VariableDescription
modelLLM_SERVICE_<MODEL_NAME>_MODEL_NAMEThe specific model identifier that the endpoint expects in the format of provider/model (e.g., openai/gpt-4, anthropic/claude-3-opus-20240229).
api_baseLLM_SERVICE_ENDPOINTThe base URL of the LLM provider's API endpoint.
api_keyLLM_SERVICE_API_KEYThe API key for authenticating with the service.
parallel_tool_callsEnable parallel tool calls for the model.
cache_strategySet the prompt caching strategy (one of: none, 5m, 1h). For more details check LLM Configuration page.
max_tokensMAX_TOKENSSet a reasonable max token limit for the model.
temperatureTEMPERATURELower temperature for more deterministic planning.

For Google's Gemini models, you can use a simplified configuration approach that references the model directly:

model: gemini-2.5-pro

For detailed information about configuring Gemini models and setting up the required environment variables, see the Gemini model documentation.

Predefined Model Types​

The shared_config.yaml configuration file defines predefined model types that serve as aliases for specific use cases. These aliases allow you to reference models by their intended purpose rather than their technical specifications, making your agent configurations more readable and maintainable. The model types are as follows:

  • planning: Used by agents for planning and decision-making. It's configured for deterministic outputs (temperature: 0.1) and can use tools in parallel.
  • general: A general-purpose model for various tasks.
  • image_gen: A model for generating images.
  • image_describe: A model for describing the content of images.
  • audio_transcription: A model for transcribing audio files.
  • report_gen: A model specialized for generating reports.
  • multimodal: A simple string reference to a multimodal model (e.g., "gemini-1.5-flash-latest").

You can define any number of models in this section and reference them in your agent configurations. The system uses only the planning and general models by default; you don't need to configure the specialized models unless your agents specifically require those capabilities.

For information about configuring different LLM providers and SSL/TLS security settings, see Configuring LLMs.

Service Configuration​

The services section in shared_config.yaml is used to configure various services that are available to agents. These services handle concerns such as session persistence, artifact storage, and data processing optimization.

Session Service​

The session service manages conversation history and context persistence across agent interactions. This service determines whether agents remember previous conversations and how long that memory persists.

ParameterOptionsDescriptionDefault
typememory, sql, vertex_ragConfiguration for ADK Session Servicememory
default_behaviorPERSISTENT, RUN_BASEDThe default behavior of keeping the session historyPERSISTENT
tip

Although the default session service type is memory, both Orchestrator Agent and Web UI gateway use sql as their session service to allow for persistent sessions.

Artifact Service​

The artifact_service is responsible for managing artifacts, which are files or data generated by agents, such as generated documents, processed data files, and intermediate results.

ParameterOptionsDescriptionDefault
typememory, gcs, filesystemService type for artifact storage. Use memory for in-memory, gcs for Google Cloud Storage, or filesystem for local file storage.memory
base_pathlocal pathBase directory path for storing artifacts. Required only if type is filesystem.(none)
bucket_namebucket nameGoogle Cloud Storage bucket name. Required only if type is gcs.(none)
artifact_scopenamespace, appScope for artifact sharing. namespace: shared by all components in the namespace. app: isolated by agent/gateway name. Must be consistent for all components in the same process.namespace
artifact_scope_valuecustom scope idCustom identifier for artifact scope. Required if artifact_scope is set to a custom value.(none)

Data Tools Configuration​

The data tools configuration optimizes how agents handle data analysis and processing tasks. These settings balance performance, memory usage, and user experience when agents work with databases and large datasets.

The SQLite memory threshold determines when the system switches from disk-based to memory-based database operations. Lower thresholds favor memory usage for better performance although consume more system RAM. Higher thresholds reduce memory pressure although may slow database operations.

Result preview settings control how much data agents display when showing query results or data samples. These limits prevent overwhelming users with massive datasets while ensuring they see enough information to understand the results.

ParameterTypeDescriptionDefault
sqlite_memory_threshold_mbintegerThe memory threshold in megabytes for using an in-memory SQLite database.100
max_result_preview_rowsintegerThe maximum number of rows to show in a result preview.50
max_result_preview_bytesintegerThe maximum number of bytes to show in a result preview.4096