1  ---
  2  title: MongoDB Integration
  3  sidebar_position: 50
  4  ---
  5  
  6  # MongoDB Integration
  7  
  8  This tutorial sets up a MongoDB agent in Agent Mesh, which allows the Agent Mesh agent to answer natural language queries about a Mongo database. The agent translates user questions into MongoDB aggregation pipelines and executes them against your database.
  9  
 10  ## Prerequisites
 11  
 12  Before starting this tutorial, ensure that you have installed and configured Agent Mesh:
 13  
 14  - [Installed Agent Mesh and the Agent Mesh CLI](../../installing-and-configuring/installation.md)
 15  - [Created a new Agent Mesh project](../../installing-and-configuring/run-project.md)
 16  - Access to a MongoDB database (local or remote)
 17  
 18  ## Adding the MongoDB Plugin
 19  
 20  Add the MongoDB plugin to your Agent Mesh project:
 21  
 22  ```sh
 23  sam plugin add coffee-shop-mongo --plugin sam-mongodb
 24  ```
 25  
 26  You can use any name for your agent, in this tutorial we use `coffee-shop-mongo`.
 27  
 28  This command:
 29  - Installs the `sam-mongodb` plugin
 30  - Creates a new agent configuration file at `configs/agents/coffee-shop-mongo.yaml`
 31  
 32  
 33  #### Setting Up Your MongoDB Database
 34  
 35  This tutorial assumes you have a MongoDB database with a collection containing coffee shop data. You can use any MongoDB database, but here is an example structure for a coffee shop:
 36  
 37  #### Example Document Structure
 38  
 39  ```json
 40  {
 41    "_id": "64a1b2c3d4e5f6789012345",
 42    "order_id": "ORD-2024-001",
 43    "customer": {
 44      "name": "John Doe",
 45      "email": "john.doe@example.com",
 46      "phone": "+1-555-0123"
 47    },
 48    "items": [
 49      {
 50        "product": "Espresso",
 51        "quantity": 2,
 52        "price": 3.50,
 53        "category": "Coffee"
 54      },
 55      {
 56        "product": "Croissant",
 57        "quantity": 1,
 58        "price": 2.75,
 59        "category": "Pastry"
 60      }
 61    ],
 62    "total_amount": 9.75,
 63    "order_date": "2024-01-15T10:30:00Z",
 64    "status": "completed",
 65    "payment_method": "credit_card",
 66    "location": "Downtown Store"
 67  }
 68  ```
 69  
 70  ## Configuring the Agent
 71  
 72  Open the `configs/agents/coffee-shop-mongo.yaml` file and modify the `agent_init_function.config` section to connect to your MongoDB database.
 73  
 74  Here is what you need to modify in the configuration file:
 75  
 76  ```yaml
 77  # Find the agent_init_function section and update the config:
 78  agent_init_function:
 79    module: "sam_mongodb.lifecycle"
 80    name: "initialize_mongo_agent"
 81    config:
 82      db_host: "${COFFEE_SHOP_MONGO_MONGO_HOST}"
 83      db_port: ${COFFEE_SHOP_MONGO_MONGO_PORT}
 84      db_user: "${COFFEE_SHOP_MONGO_MONGO_USER}"
 85      db_password: "${COFFEE_SHOP_MONGO_MONGO_PASSWORD}"
 86      db_name: "${COFFEE_SHOP_MONGO_MONGO_DB}"
 87      database_collection: "${COFFEE_SHOP_MONGO_MONGO_COLLECTION}"
 88      database_purpose: "${COFFEE_SHOP_MONGO_DB_PURPOSE}"
 89      data_description: "${COFFEE_SHOP_MONGO_DB_DESCRIPTION}"
 90      auto_detect_schema: true
 91      max_inline_results: 10
 92  ```
 93  
 94  #### Setting the Environment Variables
 95  
 96  The MongoDB agent requires several environment variables. Create or update your `.env` file with the following variables:
 97  
 98  ```bash
 99  # MongoDB Connection Settings
100  COFFEE_SHOP_MONGO_MONGO_HOST=localhost
101  COFFEE_SHOP_MONGO_MONGO_PORT=27017
102  COFFEE_SHOP_MONGO_MONGO_USER=your_username
103  COFFEE_SHOP_MONGO_MONGO_PASSWORD=your_password
104  COFFEE_SHOP_MONGO_MONGO_DB=coffee_shop
105  COFFEE_SHOP_MONGO_MONGO_COLLECTION=orders
106  
107  # Database Description
108  COFFEE_SHOP_MONGO_DB_PURPOSE="Coffee shop order management database"
109  COFFEE_SHOP_MONGO_DB_DESCRIPTION="Contains customer orders, product information, sales data, and transaction history for a coffee shop business."
110  
111  # Optional Settings
112  AUTO_DETECT_SCHEMA=true
113  MAX_INLINE_RESULTS=10
114  ```
115  
116  #### MongoDB Connection Options
117  
118  - **Local MongoDB**: Use `localhost` as the host and default port `27017`
119  - **MongoDB Atlas**: Use your Atlas connection string format
120  - **Authentication**: Provide username and password if your MongoDB requires authentication
121  - **No Authentication**: Leave username and password empty for local development databases
122  
123  ## Running the Agent
124  
125  Now you can start your MongoDB agent:
126  
127  ```sh
128  sam run configs/agents/coffee-shop-mongo.yaml
129  ```
130  
131  The agent:
132  1. Connects to the A2A control plane
133  2. Initializes the MongoDB connection
134  3. Detects the database schema automatically
135  4. Registers its capabilities with the agent discovery system
136  
137  ## Interacting with the Database
138  
139  After your MongoDB agent is running, you can interact with the database through any gateway in your Agent Mesh project (such as the Web UI gateway at `http://localhost:8000`).
140  
141  You can ask natural language questions about your MongoDB database, such as:
142  
143  - "How many orders were placed today?"
144  - "What are the most popular coffee products?"
145  - "Show me all orders from customers in New York"
146  - "What's the average order value this month?"
147  - "Find all incomplete orders"
148  - "Group orders by payment method and show totals"
149  
150  Try creating reports by asking questions such as:
151  
152  - "Create a sales report for the last 7 days"
153  - "Generate a summary of customer preferences"
154  - "Show me the top 10 customers by total spending"
155  
156  The MongoDB agent converts your natural language questions into MongoDB aggregation pipelines, executes them against the database, and returns the results. For large result sets, the agent automatically saves the results as artifacts that you can download.
157  
158  ## Advanced Configuration
159  
160  The MongoDB plugin supports many advanced configuration options. Here is a complete example based on the plugin structure:
161  
162  ```yaml
163  log:
164    stdout_log_level: INFO
165    log_file_level: DEBUG
166    log_file: coffee-shop-mongo.log
167  
168  !include ../shared_config.yaml
169  
170  apps:
171    - name: coffee-shop-mongo-app
172      app_module: solace_agent_mesh.agent.sac.app 
173      broker:
174        <<: *broker_connection
175  
176      app_config:
177        namespace: ${NAMESPACE}
178        agent_name: "CoffeeShopMongo"
179        display_name: "Coffee Shop MongoDB Agent"
180        supports_streaming: false
181        model: *general_model
182        model_provider: 
183          - "general"
184  
185        instruction: |
186          You are an expert MongoDB assistant for the coffee shop database.
187          Your primary goal is to translate user questions into accurate MongoDB aggregation pipelines.
188          When asked to query the database, generate the pipeline and call the query tool.
189          If the tool returns an error, analyze the error message and the original pipeline,
190          then try to correct the pipeline and call the tool again.
191          Always provide clear explanations of the results you find.
192  
193        # Agent initialization with database setup
194        agent_init_function:
195          module: "sam_mongodb.lifecycle"
196          name: "initialize_mongo_agent"
197          config:
198            db_host: "${COFFEE_SHOP_MONGO_MONGO_HOST}"
199            db_port: ${COFFEE_SHOP_MONGO_MONGO_PORT}
200            db_user: "${COFFEE_SHOP_MONGO_MONGO_USER}"
201            db_password: "${COFFEE_SHOP_MONGO_MONGO_PASSWORD}"
202            db_name: "${COFFEE_SHOP_MONGO_MONGO_DB}"
203            database_collection: "${COFFEE_SHOP_MONGO_MONGO_COLLECTION}"
204            database_purpose: "${COFFEE_SHOP_MONGO_DB_PURPOSE}"
205            data_description: "${COFFEE_SHOP_MONGO_DB_DESCRIPTION}"
206            auto_detect_schema: true
207            max_inline_results: 10
208  
209        agent_cleanup_function:
210          module: "sam_mongodb.lifecycle"
211          name: "cleanup_mongo_agent_resources"
212  
213        # MongoDB query tool
214        tools:
215          - tool_type: builtin-group
216            group_name: "artifact_management"
217          - tool_type: builtin-group
218            group_name: "data_analysis"
219          - tool_type: python
220            component_module: "sam_mongodb.search_query"
221            function_name: "mongo_query"
222            tool_config:
223              collection: "${COFFEE_SHOP_MONGO_MONGO_COLLECTION}"
224  
225        session_service: *default_session_service
226        artifact_service: *default_artifact_service
227  
228        # Artifact handling
229        artifact_handling_mode: "reference"
230        enable_embed_resolution: true
231        enable_artifact_content_instruction: true
232  
233        # Agent capabilities - This is what other agents see during discovery
234        agent_card:
235          description: "Coffee Shop MongoDB Agent - Access to comprehensive coffee shop order data including customer information, product details, sales transactions, and order history. Can answer questions about sales analytics, customer behavior, product performance, and business metrics."
236          defaultInputModes: ["text"]
237          defaultOutputModes: ["text", "file"]
238          skills:
239            - id: "mongo_query"
240              name: "Coffee Shop MongoDB Query"
241              description: "Queries coffee shop MongoDB database containing customer orders, product catalog, payment transactions, and order history using aggregation pipelines."
242  
243        # A2A Protocol settings
244        agent_card_publishing: { interval_seconds: 30 }
245        agent_discovery: { enabled: true }
246        inter_agent_communication:
247          allow_list: ["*"]
248          request_timeout_seconds: 60
249  ```
250  
251  ## Customizing the Agent Card
252  
253  The `agent_card` section is crucial as it defines how other agents in your Agent Mesh ecosystem discover and understand this MongoDB agent's capabilities. When other agents use agent discovery, they can see this information to decide whether to delegate tasks to your database agent.
254  
255  ### Key Agent Card Elements
256  
257  1. **Description**: Clearly describe what data the agent has access to and what types of questions it can answer
258  2. **Skills**: List specific capabilities with concrete examples that show the scope of data available
259  3. **Data Context**: Mention the business domain, data types, and scope of information available
260  
261  ### Example of a Well-Configured Agent Card
262  
263  ```yaml
264  agent_card:
265    description: "Coffee Shop MongoDB Agent - Access to comprehensive coffee shop order data including customer information, product details, sales transactions, and order history. Can answer questions about sales analytics, customer behavior, product performance, and business metrics."
266    defaultInputModes: ["text"]
267    defaultOutputModes: ["text", "file"]
268    skills:
269      - id: "mongo_query"
270        name: "Coffee Shop MongoDB Query"
271        description: "Queries coffee shop MongoDB database containing customer orders, product catalog, payment transactions, and order history using aggregation pipelines."
272  ```
273  
274  This detailed information helps other agents understand:
275  - What business domain this agent covers (coffee shop operations)
276  - What types of data are available (orders, customers, products, payments)
277  - What kinds of questions can be answered (analytics, behavior, performance, metrics)
278  - Specific examples of queries that work well with MongoDB aggregation pipelines
279  
280  When configuring your own MongoDB agent, customize the description and examples to match your specific data structure and use cases.
281  
282  ## MongoDB Query Features
283  
284  The MongoDB agent supports various types of queries through natural language:
285  
286  ### Aggregation Queries
287  - "Show me the top 5 products by sales volume"
288  - "Calculate the average order value by customer segment"
289  - "Group orders by month and show revenue trends"
290  
291  ### Filtering and Search
292  - "Find all orders placed in the last 24 hours"
293  - "Show me orders with a total amount greater than $50"
294  - "Find customers who ordered espresso drinks"
295  
296  ### Complex Analytics
297  - "What's the conversion rate from browsing to purchase?"
298  - "Show me the busiest hours of the day"
299  - "Calculate customer lifetime value"
300  
301  ### Output Formats
302  
303  The agent supports multiple output formats:
304  - **JSON**: Default format, good for structured data
305  - **YAML**: Human-readable format
306  - **CSV**: Suitable for spreadsheet import
307  - **Markdown**: Formatted for documentation
308  
309  You can specify the format in your query: "Show me today's sales in CSV format"
310  
311  ## Troubleshooting
312  
313  ### Common Issues and Solutions
314  
315  #### Connection Errors
316  **Issue**: "Unable to connect to MongoDB" errors
317  **Solution**:
318  - Verify your MongoDB server is running
319  - Check connection parameters (host, port, credentials)
320  - Ensure network connectivity and firewall settings
321  - Test connection using MongoDB client tools
322  
323  #### Authentication Errors
324  **Issue**: "Authentication failed" errors
325  **Solution**:
326  - Verify username and password are correct
327  - Check that the user has appropriate database permissions
328  - Ensure the authentication database is correct
329  
330  #### Query Errors
331  **Issue**: "Invalid aggregation pipeline" errors
332  **Solution**:
333  - The agent automatically retries with corrected pipelines
334  - Check that your natural language query is clear and specific
335  - Verify that referenced fields exist in your collection
336  
337  #### Schema Detection Issues
338  **Issue**: Agent does not understand your data structure
339  **Solution**:
340  - Ensure `auto_detect_schema` is set to `true`
341  - Provide detailed `data_description` in your configuration
342  - Check that your collection has representative sample documents