MongoDB Integration

This tutorial sets up a MongoDB agent in Solace Agent Mesh (SAM), which allows the SAM 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.

Prerequisites

Before starting this tutorial, ensure that you have installed and configured Solace Agent Mesh:

• Installed Solace Agent Mesh and the SAM CLI
• Created a new Solace Agent Mesh project
• Access to a MongoDB database (local or remote)

Adding the MongoDB Plugin

Add the MongoDB plugin to your SAM project:

sam plugin add coffee-shop-mongo --plugin sam-mongodb

You can use any name for your agent, in this tutorial we use coffee-shop-mongo.

This command:

• Installs the sam-mongodb plugin
• Creates a new agent configuration file at configs/agents/coffee-shop-mongo.yaml

Setting Up Your MongoDB Database

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:

Example Document Structure

{
  "_id": "64a1b2c3d4e5f6789012345",
  "order_id": "ORD-2024-001",
  "customer": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phone": "+1-555-0123"
  },
  "items": [
    {
      "product": "Espresso",
      "quantity": 2,
      "price": 3.50,
      "category": "Coffee"
    },
    {
      "product": "Croissant",
      "quantity": 1,
      "price": 2.75,
      "category": "Pastry"
    }
  ],
  "total_amount": 9.75,
  "order_date": "2024-01-15T10:30:00Z",
  "status": "completed",
  "payment_method": "credit_card",
  "location": "Downtown Store"
}

Configuring the Agent

Open the configs/agents/coffee-shop-mongo.yaml file and modify the agent_init_function.config section to connect to your MongoDB database.

Here is what you need to modify in the configuration file:

# Find the agent_init_function section and update the config:
agent_init_function:
  module: "sam_mongodb.lifecycle"
  name: "initialize_mongo_agent"
  config:
    db_host: "${COFFEE_SHOP_MONGO_MONGO_HOST}"
    db_port: ${COFFEE_SHOP_MONGO_MONGO_PORT}
    db_user: "${COFFEE_SHOP_MONGO_MONGO_USER}"
    db_password: "${COFFEE_SHOP_MONGO_MONGO_PASSWORD}"
    db_name: "${COFFEE_SHOP_MONGO_MONGO_DB}"
    database_collection: "${COFFEE_SHOP_MONGO_MONGO_COLLECTION}"
    database_purpose: "${COFFEE_SHOP_MONGO_DB_PURPOSE}"
    data_description: "${COFFEE_SHOP_MONGO_DB_DESCRIPTION}"
    auto_detect_schema: true
    max_inline_results: 10

Setting the Environment Variables

The MongoDB agent requires several environment variables. Create or update your .env file with the following variables:

# MongoDB Connection Settings
COFFEE_SHOP_MONGO_MONGO_HOST=localhost
COFFEE_SHOP_MONGO_MONGO_PORT=27017
COFFEE_SHOP_MONGO_MONGO_USER=your_username
COFFEE_SHOP_MONGO_MONGO_PASSWORD=your_password
COFFEE_SHOP_MONGO_MONGO_DB=coffee_shop
COFFEE_SHOP_MONGO_MONGO_COLLECTION=orders

# Database Description
COFFEE_SHOP_MONGO_DB_PURPOSE="Coffee shop order management database"
COFFEE_SHOP_MONGO_DB_DESCRIPTION="Contains customer orders, product information, sales data, and transaction history for a coffee shop business."

# Optional Settings
AUTO_DETECT_SCHEMA=true
MAX_INLINE_RESULTS=10

MongoDB Connection Options

• Local MongoDB: Use localhost as the host and default port 27017
• MongoDB Atlas: Use your Atlas connection string format
• Authentication: Provide username and password if your MongoDB requires authentication
• No Authentication: Leave username and password empty for local development databases

Running the Agent

Now you can start your MongoDB agent:

sam run configs/agents/coffee-shop-mongo.yaml

The agent:

1. Connects to the A2A control plane
2. Initializes the MongoDB connection
3. Detects the database schema automatically
4. Registers its capabilities with the agent discovery system

Interacting with the Database

After your MongoDB agent is running, you can interact with the database through any gateway in your SAM project (such as the Web UI gateway at http://localhost:8000).

You can ask natural language questions about your MongoDB database, such as:

• "How many orders were placed today?"
• "What are the most popular coffee products?"
• "Show me all orders from customers in New York"
• "What's the average order value this month?"
• "Find all incomplete orders"
• "Group orders by payment method and show totals"

Try creating reports by asking questions such as:

• "Create a sales report for the last 7 days"
• "Generate a summary of customer preferences"
• "Show me the top 10 customers by total spending"

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.

Advanced Configuration

The MongoDB plugin supports many advanced configuration options. Here is a complete example based on the plugin structure:

log:
  stdout_log_level: INFO
  log_file_level: DEBUG
  log_file: coffee-shop-mongo.log

!include ../shared_config.yaml

apps:
  - name: coffee-shop-mongo-app
    app_module: solace_agent_mesh.agent.sac.app 
    broker:
      <<: *broker_connection

    app_config:
      namespace: ${NAMESPACE}
      agent_name: "CoffeeShopMongo"
      display_name: "Coffee Shop MongoDB Agent"
      supports_streaming: false
      model: *general_model

      instruction: |
        You are an expert MongoDB assistant for the coffee shop database.
        Your primary goal is to translate user questions into accurate MongoDB aggregation pipelines.
        When asked to query the database, generate the pipeline and call the query tool.
        If the tool returns an error, analyze the error message and the original pipeline,
        then try to correct the pipeline and call the tool again.
        Always provide clear explanations of the results you find.

      # Agent initialization with database setup
      agent_init_function:
        module: "sam_mongodb.lifecycle"
        name: "initialize_mongo_agent"
        config:
          db_host: "${COFFEE_SHOP_MONGO_MONGO_HOST}"
          db_port: ${COFFEE_SHOP_MONGO_MONGO_PORT}
          db_user: "${COFFEE_SHOP_MONGO_MONGO_USER}"
          db_password: "${COFFEE_SHOP_MONGO_MONGO_PASSWORD}"
          db_name: "${COFFEE_SHOP_MONGO_MONGO_DB}"
          database_collection: "${COFFEE_SHOP_MONGO_MONGO_COLLECTION}"
          database_purpose: "${COFFEE_SHOP_MONGO_DB_PURPOSE}"
          data_description: "${COFFEE_SHOP_MONGO_DB_DESCRIPTION}"
          auto_detect_schema: true
          max_inline_results: 10

      agent_cleanup_function:
        module: "sam_mongodb.lifecycle"
        name: "cleanup_mongo_agent_resources"

      # MongoDB query tool
      tools:
        - tool_type: builtin-group
          group_name: "artifact_management"
        - tool_type: builtin-group
          group_name: "data_analysis"
        - tool_type: python
          component_module: "sam_mongodb.search_query"
          function_name: "mongo_query"
          tool_config:
            collection: "${COFFEE_SHOP_MONGO_MONGO_COLLECTION}"

      session_service: *default_session_service
      artifact_service: *default_artifact_service

      # Artifact handling
      artifact_handling_mode: "reference"
      enable_embed_resolution: true
      enable_artifact_content_instruction: true

      # Agent capabilities - This is what other agents see during discovery
      agent_card:
        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."
        defaultInputModes: ["text"]
        defaultOutputModes: ["text", "file"]
        skills:
          - id: "mongo_query"
            name: "Coffee Shop MongoDB Query"
            description: "Queries coffee shop MongoDB database containing customer orders, product catalog, payment transactions, and order history using aggregation pipelines."

      # A2A Protocol settings
      agent_card_publishing: { interval_seconds: 30 }
      agent_discovery: { enabled: true }
      inter_agent_communication:
        allow_list: ["*"]
        request_timeout_seconds: 60

Customizing the Agent Card

The agent_card section is crucial as it defines how other agents in your SAM 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.

Key Agent Card Elements

1. Description: Clearly describe what data the agent has access to and what types of questions it can answer
2. Skills: List specific capabilities with concrete examples that show the scope of data available
3. Data Context: Mention the business domain, data types, and scope of information available

Example of a Well-Configured Agent Card

agent_card:
  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."
  defaultInputModes: ["text"]
  defaultOutputModes: ["text", "file"]
  skills:
    - id: "mongo_query"
      name: "Coffee Shop MongoDB Query"
      description: "Queries coffee shop MongoDB database containing customer orders, product catalog, payment transactions, and order history using aggregation pipelines."

This detailed information helps other agents understand:

• What business domain this agent covers (coffee shop operations)
• What types of data are available (orders, customers, products, payments)
• What kinds of questions can be answered (analytics, behavior, performance, metrics)
• Specific examples of queries that work well with MongoDB aggregation pipelines

When configuring your own MongoDB agent, customize the description and examples to match your specific data structure and use cases.

MongoDB Query Features

The MongoDB agent supports various types of queries through natural language:

Aggregation Queries

• "Show me the top 5 products by sales volume"
• "Calculate the average order value by customer segment"
• "Group orders by month and show revenue trends"

Filtering and Search

• "Find all orders placed in the last 24 hours"
• "Show me orders with a total amount greater than $50"
• "Find customers who ordered espresso drinks"

Complex Analytics

• "What's the conversion rate from browsing to purchase?"
• "Show me the busiest hours of the day"
• "Calculate customer lifetime value"

Output Formats

The agent supports multiple output formats:

• JSON: Default format, good for structured data
• YAML: Human-readable format
• CSV: Suitable for spreadsheet import
• Markdown: Formatted for documentation

You can specify the format in your query: "Show me today's sales in CSV format"

Troubleshooting

Common Issues and Solutions

Connection Errors

Issue: "Unable to connect to MongoDB" errors Solution:

• Verify your MongoDB server is running
• Check connection parameters (host, port, credentials)
• Ensure network connectivity and firewall settings
• Test connection using MongoDB client tools

Authentication Errors

Issue: "Authentication failed" errors Solution:

• Verify username and password are correct
• Check that the user has appropriate database permissions
• Ensure the authentication database is correct

Query Errors

Issue: "Invalid aggregation pipeline" errors Solution:

• The agent automatically retries with corrected pipelines
• Check that your natural language query is clear and specific
• Verify that referenced fields exist in your collection

Schema Detection Issues

Issue: Agent does not understand your data structure Solution:

• Ensure auto_detect_schema is set to true
• Provide detailed data_description in your configuration
• Check that your collection has representative sample documents