diff --git a/tutorials/connect-generative-apis-sql/index.mdx b/tutorials/connect-generative-apis-sql/index.mdx new file mode 100644 index 0000000000..005156e4ec --- /dev/null +++ b/tutorials/connect-generative-apis-sql/index.mdx @@ -0,0 +1,193 @@ + +--- +meta: + title: Connect Generative APIs to Serverless SQL with the Model Context Protocol + description: Create an intelligent agent that can analyze your Serverless SQL data using natural language queries through Model Context Protocol. +content: + h1: Connect Generative APIs to Serverless SQL with the Model Context Protocol + paragraph: Create an intelligent agent that can analyze your Serverless SQL data using natural language queries through Model Context Protocol. +tags: AI MCP SQL agent python database +categories: + - generative-apis + - serverless-sql +dates: + validation: 2025-05-13 + posted: 2025-05-13 +--- + +[Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) is an open, standardized communication protocol that enables Large Language Models to interact with external tools and services through a defined interface. + +This tutorial demonstrates how to build a data analysis agent that connects Scaleway's Generative APIs with Serverless SQL using MCP. You'll learn how to create an AI agent that can: +- Understand your database schema automatically +- Convert natural language questions into SQL queries +- Execute queries and present results in a human-friendly format + + + +- A Scaleway account logged into the [console](https://console.scaleway.com) +- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing actions in the intended Organization +- Python 3.9 or higher +- An API key from Scaleway [Identity and Access Management](/iam/) +- Access to Scaleway [Generative APIs](/generative-apis/quickstart/) and [Serverless SQL](/serverless-sql/quickstart/) + +## Introduction + +The solution consists of three main components: + +1. **Generative APIs**: Provides the AI model that processes natural language queries +2. **Serverless SQL**: Stores and manages the data +3. **Local AI agent**: Coordinates between the AI model and database + + + The agent runs on a local machine in this tutorial but could also be embedded as a remote application. + + +## Configuring Scaleway services + +### Set up Generative APIs + +1. Go to the Scaleway console and navigate to **Generative APIs** +2. Select a model (Mistral Small is used for this tutorial) +3. Click **View Code* and note down the *base URL* and *model name* + +### Configure Serverless SQL + +1. Go to **Databases** > **Serverless SQL** +2. [Create a new database](/serverless-sql-databases/how-to/create-a-database/) with default settings +3. Click **Connect application** > **Connect with an existing IAM Secret Key** +4. Switch to the **Connection string** tab and copy the connection string + +### Seed the database + +[Connect to your database](/serverless-sql-databases/how-to/connect-to-a-database/) and run the following SQL to create a test schema with some data: + +```sql +CREATE TABLE Sales ( + Product VARCHAR(50), + Buyer VARCHAR(50), + Timestamp TIMESTAMP +); + +INSERT INTO Sales (Product, Buyer, Timestamp) VALUES + ('Laptop', 'Alice', NOW() - INTERVAL '2 days'), + ('Tablet', 'Bob', NOW() - INTERVAL '3 days'), + ('Webcam', 'Ivan', NOW() - INTERVAL '30 minutes'), + ('Printer', 'Judy', NOW() - INTERVAL '12 hours'); +``` + +## Setting up the development environment + +The AI Agent is built in Python using the [fast-agent](https://github.com/evalstate/fast-agent) open-source framework which has native support for the MCP protocol. + +The [postgres-mcp](https://github.com/crystaldba/postgres-mcp) MCP server is used to communicate with Serverless SQL. + +1. Install a package manager. `uv` is the recommended package manager by `fast-agent`: + ```bash + curl -LsSf https://astral.sh/uv/install.sh | sh + ``` + +2. Create and activate a virtual environment: + ```bash + uv venv + ``` + +3. Install required libraries: + ```bash + uv pip install fast-agent-mcp postgres-mcp + ``` + +These libraries work together to create a secure and efficient bridge between the AI model and your database. + +## Creating the AI Agent + +### Configure the agent + +Create a file called `fastagent.config.yaml`: + +```yaml +default_model: "generic." + +generic: + api_key: "" + base_url: "" + +mcp: + servers: + database: + command: "uv" + args: ["run", "postgres-mcp"] + env: + DATABASE_URI: "" +``` + +### Create the agent script + +Create a file called `agent.py` which will contain your agent logic. + +1. Import the necessary modules and initialize the agent: + ```python + import asyncio + from mcp_agent.core.fastagent import FastAgent + + fast = FastAgent("AI Agent") + ``` + +2. Create agents with different responsibilities: + ```python + @fast.agent( + "db_schema_reader", + instruction="""Get the details of the 'sales' table in the 'public' schema of the database, which contains the sales data. Only return the column names and types.""", + servers=["database"], + ) + @fast.agent( + "query_writer", + instruction="""Write a SQL query to fetch the sales data from the database (sales table) given the input constraint. Only return the SQL query, no other text.""" + ) + @fast.agent( + "query_executor", + instruction="""Execute the following SQL statement on the database and write the results in JSON format""", + servers=["database"], + ) + ``` + + + Each agent has a specific role. Some agents need direct database access through the MCP server (using the `servers=["database"]` parameter) while others don't + + +3. Create an orchestrator that coordinates the specialized agents: + ```python + @fast.orchestrator( + name="sales_analyst", + agents=["db_schema_reader","query_writer","query_executor"], + plan_type="iterative", + plan_iterations=4, + instruction="You are a sales analyst given an input criteria. Describe the corresponding sales data from the database in one sentence." + ) + ``` + The orchestrator: + - Determines which agents to use and in what order + - Sets an overall goal for the agent system + - Uses an iterative planning approach to refine the results + - Limits the number of iterations to prevent infinite loops + +4. Create an entrypoint running the data analysis query **Get sales from last day**: + ```python + async def main() -> None: + async with fast.run() as agent: + await agent.sales_analyst("Get sales from last day") + + if __name__ == "__main__": + asyncio.run(main()) + ``` + +5. Run the script with: + ```bash + python agent.py + ``` + +The `fast-agent` framework provides details of all operations and outputs its data analysis: + + The sales data from the last day includes two transactions: a webcam purchased by Ivan at 14:52 and a printer purchased by Judy at 03:22. + + +This tutorial demonstrated how to create an AI agent that can analyze your SQL database using natural language queries. By combining Scaleway **Generative APIs** with **Serverless SQL** through Model Context Protocol, you can create powerful tools that are accessible to non-technical users.