From a9db758927011f9f7598c656c9d9b8cb5f8bf9eb Mon Sep 17 00:00:00 2001
From: Daniel Oliveira <daniel-oliveira-11@hotmail.com>
Date: Mon, 8 Jun 2026 20:20:55 +0100
Subject: [PATCH] =?UTF-8?q?docs(guide):=20add=20tutorial=20=E2=80=94=20get?=
 =?UTF-8?q?ting=20started?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/guide/tutorial-getting-started.md | 73 ++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 docs/guide/tutorial-getting-started.md

diff --git a/docs/guide/tutorial-getting-started.md b/docs/guide/tutorial-getting-started.md
new file mode 100644
index 0000000..2cd1443
--- /dev/null
+++ b/docs/guide/tutorial-getting-started.md
@@ -0,0 +1,73 @@
+# Get started: your first schema-aware query
+
+This tutorial walks you, a .NET developer, from an empty project to a running console app that answers a plain-English question about your database. By the end you will have wired AgentQL into dependency injection and watched a language model write and run SQL against your own EF Core model.
+
+## Before you start
+
+You need:
+
+- .NET 10 SDK installed.
+- An existing EF Core `DbContext` (this tutorial uses one called `MyDbContext`).
+- An API key for a supported AI provider (OpenAI is used here).
+
+## 1. Install the package
+
+Add the full-stack package, which bundles schema introspection, query execution, and the AI chat bridge:
+
+```bash
+dotnet add package Equibles.AgentQL.MicrosoftAI
+```
+
+You should see the package and its dependencies restore without errors.
+
+## 2. Register AgentQL with dependency injection
+
+In your startup code, register your `DbContext` and then call `AddAgentQLChat`:
+
+```csharp
+builder.Services.AddDbContext<MyDbContext>(o => o.UseSqlite("DataSource=app.db"));
+
+builder.Services.AddAgentQLChat<MyDbContext>(configureChat: options =>
+{
+    options.Provider = AiProvider.OpenAI;
+    options.ApiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY");
+    options.ModelName = "gpt-4o";
+});
+```
+
+This single call registers `ISchemaProvider`, `IQueryExecutor`, `AgentQLPlugin`, and `IChatClient` — everything you need is now available from the service provider.
+
+## 3. Ask a question
+
+Resolve the chat client and the plugin, expose the plugin's functions as tools, and send a question:
+
+```csharp
+using var scope = serviceProvider.CreateScope();
+var chatClient = scope.ServiceProvider.GetRequiredService<IChatClient>();
+var plugin = scope.ServiceProvider.GetRequiredService<AgentQLPlugin>();
+
+var chatOptions = new ChatOptions { Tools = [.. AIFunctionFactory.Create(plugin)] };
+
+var messages = new List<ChatMessage>
+{
+    new(ChatRole.System, "You are a helpful database assistant."),
+    new(ChatRole.User, "How many customers signed up last month?"),
+};
+
+var response = await chatClient.GetResponseAsync(messages, chatOptions);
+Console.WriteLine(response);
+```
+
+## 4. See what happened
+
+Behind the scenes the model called `GetDatabaseSchema` to learn your tables and columns, wrote a `SELECT`, called `ExecuteQuery` to run it, and turned the rows into an answer such as:
+
+```
+There were 42 customers who signed up last month.
+```
+
+You did not write any SQL — the model did, grounded in your real schema.
+
+## What you achieved and what's next
+
+You installed AgentQL, registered it in one call, and got a language model to answer a question by querying your database. To keep going, return to the [user guide index](README.md) for how-to guides on choosing a provider, controlling which tables the model can see, and keeping execution read-only.