{"id":26739986,"url":"https://github.com/kbeaugrand/semantickernel.agents.databaseagent","last_synced_at":"2025-09-24T16:12:22.521Z","repository":{"id":284207316,"uuid":"953179441","full_name":"kbeaugrand/SemanticKernel.Agents.DatabaseAgent","owner":"kbeaugrand","description":"Database agent for Semantic Kernel","archived":false,"fork":false,"pushed_at":"2025-03-24T17:34:04.000Z","size":10897,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-24T18:39:35.850Z","etag":null,"topics":["ai","dbms","llm","nl2sql","semantic-kernel"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kbeaugrand.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-22T18:47:18.000Z","updated_at":"2025-03-24T17:34:09.000Z","dependencies_parsed_at":"2025-03-24T22:01:19.347Z","dependency_job_id":null,"html_url":"https://github.com/kbeaugrand/SemanticKernel.Agents.DatabaseAgent","commit_stats":null,"previous_names":["kbeaugrand/semantickernel.agents.databaseagent"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kbeaugrand%2FSemanticKernel.Agents.DatabaseAgent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kbeaugrand%2FSemanticKernel.Agents.DatabaseAgent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kbeaugrand%2FSemanticKernel.Agents.DatabaseAgent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kbeaugrand%2FSemanticKernel.Agents.DatabaseAgent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kbeaugrand","download_url":"https://codeload.github.com/kbeaugrand/SemanticKernel.Agents.DatabaseAgent/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245972667,"owners_count":20702721,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","dbms","llm","nl2sql","semantic-kernel"],"created_at":"2025-03-28T04:48:25.204Z","updated_at":"2025-09-24T16:12:22.504Z","avatar_url":"https://github.com/kbeaugrand.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Database Agent for Semantic Kernel\n\n[![Build \u0026 Test](https://github.com/kbeaugrand/SemanticKernel.Agents.DatabaseAgent/actions/workflows/build_tests.yml/badge.svg)](https://github.com/kbeaugrand/SemanticKernel.Agents.DatabaseAgent/actions/workflows/build_test.yml)\n[![Create Release](https://github.com/kbeaugrand/SemanticKernel.Agents.DatabaseAgent/actions/workflows/publish.yml/badge.svg)](https://github.com/kbeaugrand/SemanticKernel.Agents.DatabaseAgent/actions/workflows/publish.yml)\n[![Version](https://img.shields.io/github/v/release/kbeaugrand/SemanticKernel.Agents.DatabaseAgent)](https://img.shields.io/github/v/release/kbeaugrand/SemanticKernel.Agents.DatabaseAgent)\n[![License](https://img.shields.io/github/license/kbeaugrand/SemanticKernel.Agents.DatabaseAgent)](https://img.shields.io/github/v/release/kbeaugrand/SemanticKernel.Agents.DatabaseAgent)\n\n## Overview\n\nThe Database Agent for Semantic Kernel is a service that provides a database management system (DBMS) for the Semantic Kernel (NL2SQL). The Agent is responsible for managing the storage and retrieval of data from the Semantic Kernel. \nThis built on top of the [Microsoft's Semantic Kernel](https://github.com/microsoft/semantic-kernel) and Semantic Kernel Memory connectors to memorize database schema and relationships to provide a more efficient and accurate database management system.\n\n\u003cimg alt=\"image\" src=\"https://github.com/user-attachments/assets/adff6bac-440b-46d6-a0b3-a4fa84679c17\" /\u003e\n\n\n## Models Tested\n\n| Model Family | Model Name          | NL 2 SQL  | Quality Insurance |   Score    | Speed (avg time/op.)   |\n|--------------|---------------------|:---------:|:----------------:|:-----------:|:----------------------:|\n| OpenAI       | gpt-4.1-mini        | ✅        | ✅               |     100%   |     Fast (~3sec)       |\n| OpenAI       | gpt-4o-mini         | ✅        | ✅               |     90%    |     Fast (~3sec)       |\n| Phi          | phi4:14b            | ✅        | ✅               |     70%    |     Medium (~10sec)    |\n| Meta         | llama4:scout        | ✅        | ✅               |     70%    |     Medium (~10sec)    |\n| MistralAI    | magistral:24b       | ✅        | ✅               |     90%    |     Medium (~10sec)    |\n| MistralAI    | devstral:24b        | ✅        | ✅               |     70%    |     Medium (~10sec)    |\n| Qwen         | qwen3:30b-a3b       | ✅        | ✅               |     80%    |     Medium (~10sec)    |\n| Qwen         | qwen3:14b           | ⚠️ (WIP)  | ⚠️ (WIP)         |     50%    |     Medium (~10sec)    |\n| Qwen         | qwen3:8b            | ⚠️ (WIP)  | ⚠️ (WIP)         |     50%    |     Medium (~10sec)    |\n| Qwen         | qwen2.5-coder:7b    | ⚠️ (WIP)  | ⚠️ (WIP)         |     30%    |     Fast (~3sec)       |\n\n\u003e Note: current score is a personal evaluation regarding the test cases with Northwind database and a set of queries.\n\u003e       development is firstly focused on the gpt-4o-mini model, which is the most performant and accurate model for NL2SQL tasks.\n\u003e       for the evaluation, the TopP and Temperature parameters are set to 0.1, which is the recommended setting.\n\n**DICLAIMER**\n\nEven if the model is marked as tested, it does not mean that it will work for all queries. \n\nFurthermore, **using LLM agents might lead to risks such as unintended data exposure, security vulnerabilities, and inefficient query execution, potentially compromising system integrity and compliance requirements.**\n\n## Getting Started\n\n### Prerequisites\n\n- [.NET 8.0 SDK](https://dotnet.microsoft.com/download/dotnet/8.0)\n\n### Installation\n\nTo use the Database Agent for Semantic Kernel, you must first install the package from NuGet.\n\n```bash\ndotnet add package SemanticKernel.Agents.DatabaseAgent\n```\n\n### Usage\n\nTo use the Database Agent for Semantic Kernel, you must first create an instance of the `DatabaseAgent` class and provide the necessary configuration settings.\n\n```csharp\nusing Microsoft.KernelMemory;\nusing Microsoft.SemanticKernel;\nusing Microsoft.SemanticKernel.ChatCompletion;\nusing SemanticKernel.Agents.DatabaseAgent;\n\nvar kernelBuilder = Kernel.CreateBuilder()\n                ...\n                .Build();\n\nkernelBuilder.Services.AddSingleton\u003cDbConnection\u003e((sp) =\u003e\n            {\n                // Configure the database connection\n                return new SqliteConnection(configuration.GetConnectionString(\"DefaultConnection\"));\n            });\n\nvar kernel = kernelBuilder.Build();\n\nvar agent = await DBMSAgentFactory.CreateAgentAsync(kernel);\n\n// execute the NL2SQL query\nvar responses = agent.InvokeAsync([new ChatMessageContent { Content = question, Role = AuthorRole.User }], thread: null)\n                                            .ConfigureAwait(false);\n```\n\n## Install the MCP Server as a Docker Image\n\nThe database agent MCP server can be run as a Docker image. This allows you to run the server in a containerized environment, making it easy to deploy and manage to expose it SSE (Server-Sent Events) and HTTP endpoints. \n\nTo run the MCP server as a Docker image, you can use the following command:\n\n```bash\n\ndocker run -it --rm \\\n  -p 8080:5000 \\\n  -e AGENT__TRANSPORT__KIND=Sse \\\n  -e ASPNETCORE_URLS=http://+:5000 \\\n  -e DATABASE_PROVIDER=sqlite \\\n  -e DATABASE_CONNECTION_STRING=\"Data Source=northwind.db;Mode=ReadWrite\" \\\n  -e MEMORY_KIND=Volatile \\\n  -e KERNEL_COMPLETION=gpt4omini \\\n  -e KERNEL_EMBEDDING=textembeddingada002 \\\n  -e SERVICES_GPT4OMINI_TYPE=AzureOpenAI \\\n  -e SERVICES_GPT4OMINI_ENDPOINT=https://xxx.openai.azure.com/ \\\n  -e SERVICES_GPT4OMINI_AUTH=APIKey \\\n  -e SERVICES_GPT4OMINI_API_KEY=xxx \\\n  -e SERVICES_GPT4OMINI_DEPLOYMENT=gpt-4o-mini \\\n  -e SERVICES_TEXTEMBEDDINGADA002_TYPE=AzureOpenAI \\\n  -e SERVICES_TEXTEMBEDDINGADA002_ENDPOINT=https://xxx.openai.azure.com/ \\\n  -e SERVICES_TEXTEMBEDDINGADA002_AUTH=APIKey \\\n  -e SERVICES_TEXTEMBEDDINGADA002_API_KEY=xxx \\\n  -e SERVICES_TEXTEMBEDDINGADA002_DEPLOYMENT=text-embedding-ada-002 \\\n  ghcr.io/kbeaugrand/database-mcp-server\n```\n\nThen you can configure your favorite MCP Client like Claude Desktop with this settings: \n```json\n{\n  \"mcpServers\": {\n    \"mcp-database-agent\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote\",\n        \"http://localhost:8080/sse\",\n        \"--allow-http\"\n      ]\n    }\n  }\n}\n```\n\n### Behind the scenes\n\nHere is a simplified sequence diagram of how the Database Agent is constructed using the Semantic Kernel before it can be used:\n\n```mermaid\nsequenceDiagram\n    autonumber\n    participant Client\n    participant DatabaseAgentFactory\n    participant SemanticKernel\n    participant Database\n\n    Client-\u003e\u003eDatabaseAgentFactory: CreateAgentAsync(kernel)\n    DatabaseAgentFactory-\u003e\u003eSemanticKernel: Access services (vector store, embedding, prompts)\n\n    DatabaseAgentFactory-\u003e\u003eDatabaseAgentFactory: MemorizeAgentSchema()\n    DatabaseAgentFactory-\u003e\u003eDatabase: Fetch list of tables\n    loop For each table\n        DatabaseAgentFactory-\u003e\u003eDatabase: Get structure and data sample\n        DatabaseAgentFactory-\u003e\u003eSemanticKernel: Generate table description\n        DatabaseAgentFactory-\u003e\u003eSemanticKernel: Embed and store definition\n    end\n\n    DatabaseAgentFactory-\u003e\u003eSemanticKernel: Generate agent description\n    DatabaseAgentFactory-\u003e\u003eSemanticKernel: Generate name and instructions\n    DatabaseAgentFactory-\u003e\u003eSemanticKernel: Embed and store agent\n\n    DatabaseAgentFactory--\u003e\u003eClient: Return DatabaseKernelAgent\n```\n\nThen, once the agent is created, the client can use it to execute queries.\n\n```mermaid\nsequenceDiagram\n    autonumber\n    participant User\n    participant DatabasePlugin\n    participant SemanticKernel\n    participant Database\n\n    User-\u003e\u003eDatabasePlugin: ExecuteQueryAsync(prompt)\n\n    DatabasePlugin-\u003e\u003eSemanticKernel: Generate embedding for prompt\n    SemanticKernel--\u003e\u003eDatabasePlugin: Embedding\n\n    DatabasePlugin-\u003e\u003eSemanticKernel: Vector search for related tables\n    SemanticKernel--\u003e\u003eDatabasePlugin: Matching table definitions\n\n    DatabasePlugin-\u003e\u003eSemanticKernel: Generate SQL query (WriteSQLQuery prompt)\n    SemanticKernel--\u003e\u003eDatabasePlugin: SQL query string\n\n    DatabasePlugin-\u003e\u003eDatabasePlugin: Check query filters (optional)\n    alt Query is allowed\n        DatabasePlugin-\u003e\u003eDatabase: Execute SQL query\n        Database--\u003e\u003eDatabasePlugin: Query result\n        DatabasePlugin--\u003e\u003eUser: Markdown-formatted result\n    else Query is blocked\n        DatabasePlugin--\u003e\u003eUser: Filter message\n    end\n\n    Note over DatabasePlugin: Logs and error handling during the process\n\n```\n\n## Quality insurance\n\nUsing LLM agents to write and execute its own queries into a database might lead to risks such as unintended data exposure, security vulnerabilities, and inefficient query execution, potentially compromising system integrity and compliance requirements.\nTo mitigate these risks, the Database Agent for Semantic Kernel provides a set of quality assurance features to ensure the safety and reliability of the queries executed by the agent.\n\n### Additional Configuration\n\nFirst, you must add the ``QualityAssurance`` package for DatabaseAgent to your project.\n\n```bash\ndotnet add package SemanticKernel.Agents.DatabaseAgent.QualityAssurance\n```\n\nNext, you must configure the quality insurance settings for the Database Agent.\n```csharp\n    kernelBuilder.Services.UseDatabaseAgentQualityAssurance(opts =\u003e\n                            {\n                                opts.EnableQueryRelevancyFilter = true;\n                                opts.QueryRelevancyThreshold = .8f;\n                            });\n```\n\n### Quality Assurance Features\n\nThe Database Agent for Semantic Kernel provides the following quality assurance features:\n`QueryRelevancyFilter`: Ensures that only relevant queries are executed by the agent. The filter uses LLM to generate the description of the query that is intended to be executed, then compute the cosine similarity between the user prompt and the generated description. If the similarity score is below the threshold, the query is rejected.\n\n### Create a custom quality assurance filter\n\nYou can create a custom quality assurance filter by implementing the `IQueryExecutionFilter` interface and registering it with the DI container.\n```csharp\nkernelBuilder.Services.AddTransient\u003cIQueryExecutionFilter, CustomQueryExecutionFilter\u003e();\n\npublic class CustomQueryExecutionFilter : IQueryExecutionFilter\n{\n    public async Task OnQueryExecutionAsync(QueryExecutionContext context, Func\u003cQueryExecutionContext, Task\u003e next)\n    {\n        // Implement custom query execution logic\n        return Task.FromResult(true);\n    }\n}\n```\n\n## Contributing\n\nWe welcome contributions to enhance this project. Please fork the repository and submit a pull request with your proposed changes.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE.md) file for details.\n\n## Acknowledgments\n\n- [Microsoft's Kernel Memory](https://github.com/microsoft/kernel-memory) for providing the foundational AI service.\n- The open-source community for continuous support and contributions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkbeaugrand%2Fsemantickernel.agents.databaseagent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkbeaugrand%2Fsemantickernel.agents.databaseagent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkbeaugrand%2Fsemantickernel.agents.databaseagent/lists"}