Skip to main content

Tutorial – Building an SQL Database Agent: Commercial Assistant & Multi-Agent Collaboration

Overview​

This guide will walk you through creating a Commercial Assistant Agent in Pupau that connects directly to an SQL database for real-time business queries and reporting as shown in our YouTube Tutorial. You’ll also explore how to enable agent collaboration, empowering your assistant to work alongside others (e.g., for visualization or deeper analysis) in a multi-agent scenario. This approach is suitable for sales, inventory, CRM, or any use case requiring instant data access and teamwork. Use this example as a starting point and customize it to fit your specific needs on your SQL database and workflow. You might also want to give the agent read-only access to the database depending on your use case.


1. Introduction​

An SQL Database Agent on Pupau can read and manipulate business data live from your company databases, automate commercial reports, provide insights to your sales team, and interact with other agents for enhanced results. By configuring tools and prompts, you can quickly set up robust agents—no coding required. This tutorial follows the process shown in the "Tutorial – Agente che Accede a un Database SQL – Assistente Commerciale e Collaborazione Multiagente" workshop.

2. Create Your New Agent​

  1. Log in to Pupau: Access Pupau with proper permissions.

  2. Create Agent:

    • Click Create New Assistant (+ button).
    • Name: E.g., Sales Data Assistant or Commercial SQL Agent.
    • Description: "Connects to SQL databases to provide live business insights, statistics, and customer analytics."
    • Model: Choose GPT-4.1 Global or your preferred model.
    • System Prompt: Use a placeholder for now; you’ll customize it later.
    • Features: Disable unnecessary features (like built-in Web Search/URL Navigation if you only want database access). Keep attachments and multi-agent collaboration enabled for advanced workflows.

3. Tool Setup​

a) SQL Database Access Tool​

This tool gives the agent the ability to access the database and execute SQL queries. Be careful to give the agent the proper permissions to access the database, depending on your use case. Enforce the permission within the database IAM, i.e. creating a read only user for the agent. - Type: Native or External Tool (Database/SQL connector)

  • Name: database_access
  • Description: "Access the ERP/CRM database for CRUD operations."
  • Configuration:
    • Database type: E.g., MySQL, PostgreSQL, SQL Server — set according to your backend.
    • Host/Port: Fill in your database address and port (e.g., mycompany.com:3306).
    • Database name: Put your production or test database name (e.g., company_sales).
    • Authentication/Credentials: Use Pupau’s secure vault for storing & accessing credentials—assign the proper permissions at organization or user level.
    • Custom parameters: Leave the SQL query field dynamic so the agent can generate and execute various queries as needed.

4. System Prompt​

Your system prompt defines your agent’s operational behavior, language, and automation logic. Here you can find an example of a system prompt that you can use as a starting point.

<instructions>
<usage_info>

# AI Commercial Assistant

## Identity and Purpose

You are a knowledgeable, helpful and friendly assistant that provides accurate commercial information accessing the Database using the database_access Tool. In order to execute user request do all the sql query needed (tool invocations) and ask the user for details if something is not clear about its request.  


## Available Tools

- ** database_access ** : Access the ERP/CRM database to perform CRUD Operations


<options_usage_info>
- If you are in a situation where you need to give a multiple choice option to the user, you can use the <options> tag.
- Place the <options> tag where it fits more based on your opinion, inside the normal response section.
- Each <option> represents a button that the user can press.
- The 'prompt' value represents the new prompt that will be sent when pressing the <option> button.
- When the user selects an option, they will see the 'prompt' value as a message of their own, so keep this in mind when generating the 'prompt' value.
- The text between the <option> tags, represent the text that is seen on the button, the button text should be short and exhaustive.
- If the options represent a quiz place the correct answer in a **random** position.
- Follow this structure:

<options>
  <option prompt='The prompt the user will see as their own when they press this option'>
    The text the user will see on the button
  </option>
  <option prompt='The prompt the user will see as their own when they press this option'>
    The text the user will see on the button
  </option>
</options>

<options_example_question>
Let's imagine the user asked you about android development and you responded that Kotlin and Flutter are commonly used. Then you could ask them: 'What would you like to explore more?', this is an example of the <options> that you could generate:
<options>
  <option prompt='I would like to explore Kotlin'>
    Kotlin
  </option>
  <option prompt='I would like to explore Flutter'>
    Flutter
  </option>
</options>
</options_example_question>
<options_example_quiz>
Let's imagine the user asked for a random quiz on Italy and you asked them: 'What is the capital of Italy?', this is an example of the <options> that you could generate:
<options>
  <option prompt='Italy's capital is Turin'>
    Turin
  </option>
  <option prompt='Italy's capital is Rome'>
    Rome
  </option>
  <option prompt='Italy's capital is Milan'>
    Milan
  </option>
</options>
</options_example_quiz>
</options_usage_info>

</tags_usage_info>
</instructions>


<database>
To interact the database use MYSQL Syntax
The Database have the following tables:

Table: customers
id: int(11), chiave primaria, auto_increment
name: varchar(100), obbligatorio
surname: varchar(100), obbligatorio
address: varchar(255), opzionale
email: varchar(150), obbligatorio, unico

Table: order_items
id: int(11), chiave primaria, auto_increment
order_id: int(11), obbligatorio (collegamento con tabella orders)
product_id: int(11), obbligatorio (collegamento con tabella products)
quantity: int(11), obbligatorio
price: decimal(10,2), obbligatorio

Table: orders
id: int(11), chiave primaria, auto_increment
customer_id: int(11), obbligatorio (collegamento con customers)
order_date: datetime, obbligatorio
status: varchar(30), obbligatorio
shipping_address: varchar(255), opzionale
total: decimal(10,2), opzionale

Table: products
id: int(11), chiave primaria, auto_increment
name: varchar(255), obbligatorio
description: varchar(2048), obbligatorio
price: decimal(10,0), obbligatorio
stock_quantity: int(11), obbligatorio

</database>

5. Database Table & Structure Awareness​

For best performance, inform your agent about the main tables and schemas used along with the relationships between them and the meaning of the columns. This will help the agent to understand the data and to generate more accurate queries. The agent could autonomously interrogate the database to obtain the table list and the structure of the tables, but this will take more time and will slow down the interaction. (You can obtain table lists by running a "show tables" or describing the structure from your SQL backend.)

  • Pro-Tip: Paste table structures, relationships, and example rows into your system prompt to improve query accuracy and business reasoning. In our System Prompt example we have added the table structure and the relationships between them inside the <database> tag.

6. Example SQL Query Scenarios​

With your agent configured, test these typical business queries:

  • "Who was our top customer in 2025?"
  • "What did customer Emanuele Conti purchase?"
  • "Show me all orders grouped by customer."
  • "What’s our current inventory breakdown?"
  • "List the 10 most popular products by sales volume."
  • "How much did customer Andrea spend?"
  • "Show full data for stock, deliveries, or any business metric available."

If you’ve enabled agent-to-agent collaboration, prompt the Visualization Agent for a pie chart or other analytics, e.g.:
"Show a pie chart of the top 10 products in inventory based on volume."

7. Multi-Agent Collaboration​

To collaborate with other agents:

  • Tag another agent in the conversation using @ and select the agent from the context menu.
  • The secondary agent (e.g., Bob) can interpret the current data, create diagrams, dashboards, or deep analyses, then return results for your workflow or for user-facing reporting.

This enables highly flexible teamwork between agents: the SQL Agent retrieves and processes data, and the Visualization Agent presents it attractively to users.

8. Human Interaction & Option Buttons​

Leverage Pupau's options feature:

  • Use <options> configuration in your prompt so the agent can suggest pre-defined questions or display multi-choice buttons—improving user experience and speeding up standard queries. In our System Prompt example we have added the <options> tag to ask the user for more details about the request. You can find more information about the <options> tag in the Option Tag Documentation.

9. Testing Your Agent​

  • Ask direct business questions and confirm the agent runs real SQL queries.
  • Examine the system’s logs and SQL command results to ensure correctness.
  • Try in-depth queries (e.g., aggregations, group by, joins) for sales, inventory, or customer analytics.
  • Test collaboration: Tag your visualization agent and ensure correct graphs or summary tables are created.

10. Security & Deployment Notes​

  • Double-check database credentials, permissions, and authentication for security best practices.
  • Use test databases before connecting to production.
  • Store sensitive information only in the Pupau secure vault.

11. Next Steps​

  • Refine your system prompt for your business logic and tone.
  • Fine-tune your SQL tool’s permissions to avoid unwanted data modifications.
  • Develop specialized prompts and templates for your team or clients.
  • Explore integration with APIs, dashboards, or existing business tools for end-to-end automation.
  • Browse Pupau Marketplace for ready-made, open agents like "Bob" to speed up your deployments.

You’re ready to launch a powerful Commercial SQL Agent on Pupau! By leveraging direct database access and multi-agent collaboration, your team can scale up data-driven operations with ease and reliability.