آموزش پروتکل AG-UI با SDK رسمی دات‌نت

۱. مقدمه

این موضوع چیه؟

AG-UI مخفف Agent-User Interaction Protocol است. یعنی یک زبان مشترک بین ایجنت‌های هوش مصنوعی و رابط‌های کاربری. وقتی ایجنت می‌خواهد پیامی نشان بدهد، ابزاری صدا بزند یا کارش تمام شود، این اطلاعات را به‌صورت رویدادهای استاندارد برای UI ارسال می‌کند.

حالا که پروتکل AG-UI یک SDK رسمی برای دات‌نت دارد، دیگر لازم نیست همه چیز را دستی پیاده‌سازی کنی. با چند خط کد می‌توانی یک endpoint آماده داشته باشی که هر فرانت‌اندی آن را بفهمد.

چرا باید یادش بگیری؟

• بدون نیاز به دانش عمیق از WebSocket یا SSE، ایجنت را به UI وصل می‌کنی.
• فرانت‌اند و بک‌اند از هم جدا می‌مانند.
• ابزارها، پیام‌ها و وضعیت اجرا به‌صورت استاندارد منتقل می‌شوند.
• مقیاس‌پذیری و توسعه چت‌بات‌ها، دستیارها و پشتیبان‌ها ساده‌تر می‌شود.

کجا استفاده می‌شود؟

• چت‌بات‌های پشتیبانی
• دستیارهای داخل داشبورد
• برنامه‌های Copilot
• ابزارهای هوش مصنوعی در سایت‌های فروشگاهی

۲. پیش‌نیازها

چیزهایی که باید از قبل بدانی

• مفاهیم اولیه C# و ASP.NET Core
• آشنایی خیلی ساده با Minimal API
• مفهوم کلی HTTP و اینکه داده می‌تواند به‌صورت جریان ارسال شود

ابزارهای لازم

• .NET SDK نسخه ۸ یا ۹
• Visual Studio Code یا Visual Studio
• دسترسی به یک مدل زبانی مثل OpenAI یا Azure OpenAI (برای شروع می‌توانی از مدل‌های رایگان هم استفاده کنی)

۳. نصب و راه‌اندازی

گام ۱: ساخت پروژه جدید

dotnet new web -n AguiDemo
cd AguiDemo

گام ۲: اضافه کردن پکیج SDK

dotnet add package Microsoft.Agents.AI.AspNetCore

این پکیج شامل قابلیت‌های اصلی برای ساخت ایجنت و endpoint پروتکل AG-UI است.

گام ۳: اولین برنامه

فایل Program.cs را باز کن و کد زیر را قرار بده:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "AG-UI Demo is running!");

app.Run();

حالا با دستور زیر پروژه را اجرا کن:

dotnet run

اگر در مرورگر آدرس http://localhost:5000 را باز کنی، باید پیام ساده را ببینی. این یعنی پروژه آماده است.

۴. مفاهیم پایه

ایجنت چیست؟

ایجنت یک سرویس هوشمند است که پیام کاربر را می‌گیرد، تصمیم می‌گیرد و پاسخ می‌دهد. ممکن است از یک مدل زبانی، یک ابزار یا هر دو استفاده کند.

ChatClient چیست؟

در دات‌نت، ChatClient همان موتور گفتگو است. یک ایجنت معمولاً از آن برای تولید پاسخ استفاده می‌کند.

AG-UI Endpoint چیست؟

یک مسیر HTTP که به‌جای برگرداندن یک JSON ساده، رویدادها را به‌صورت جریان برای UI ارسال می‌کند. این جریان معمولاً با SSE یا WebSocket پیاده‌سازی می‌شود.

رویدادهای مهم AG-UI

رویداد	معنی
RunStarted	اجرای ایجنت شروع شد
TextMessage	یک تکه پیام متنی از طرف ایجنت تولید شد
ToolCall	ایجنت ابزاری را صدا زد
StateDelta	بخشی از وضعیت تغییر کرد
RunFinished	اجرای ایجنت تمام شد

یک مثال ساده از شکل داده

{ "type": "TEXT_MESSAGE_CONTENT", "content": "سلام! چطور می‌توانم کمکت کنم؟" }

این یک رویداد متنی ساده است. UI با شنیدن این رویداد، متن را به کاربر نشان می‌دهد.

۵. مثال‌های کد ساده

مثال ۱: endpoint دستی برای درک پروتکل

قبل از اینکه از SDK استفاده کنیم، ببینیم پشت صحنه چه اتفاقی می‌افتد:

using System.Text.Json;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapPost("/agent", async (HttpContext ctx) =>
{
    ctx.Response.ContentType = "text/event-stream";
    ctx.Response.Headers.CacheControl = "no-cache";

    await ctx.Response.WriteAsync($"data: {JsonSerializer.Serialize(new { type = "RUN_STARTED" })}\n\n");
    await ctx.Response.WriteAsync($"data: {JsonSerializer.Serialize(new { type = "TEXT_MESSAGE_CONTENT", content = "سلام! من آماده‌ام." })}\n\n");
    await ctx.Response.WriteAsync($"data: {JsonSerializer.Serialize(new { type = "RUN_FINISHED" })}\n\n");
});

app.Run();

توضیح ساده:

• text/event-stream یعنی خروجی از نوع SSE است.
• هر رویداد با data: شروع می‌شود و با دو خط خالی تمام می‌شود.
• سه رویداد استاندارد ارسال می‌کنیم: شروع، پیام متنی، پایان.

مثال ۲: استفاده از SDK به‌جای کد دستی

با SDK رسمی، همین کار خیلی تمیزتر می‌شود:

using Microsoft.Agents.AI;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<IChatClient>(sp =>
{
    // در اینجا ChatClient واقعی خود را ثبت کن
    var client = new OpenAIClient("YOUR_API_KEY");
    return client.AsChatClient("gpt-4o-mini");
});

builder.Services.AddAgent<SupportAgent>();

var app = builder.Build();

app.MapAgent<SupportAgent>("/agent");

app.Run();

public class SupportAgent
{
    public string Name => "SupportBot";
    public string Description => "پشتیبان ساده";
    public string Instructions => "جواب‌های کوتاه و مفید بده.";
}

در این کد، MapAgent خودش پروتکل AG-UI را پیاده‌سازی می‌کند. دیگر لازم نیست نگران ساختار SSE باشی.

مثال ۳: خواندن خروجی در فرانت‌اند

const response = await fetch('/agent', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        messages: [{ role: 'user', content: 'سلام' }]
    })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const text = decoder.decode(value);
    for (const line of text.split('\n')) {
        if (line.startsWith('data: ')) {
            const event = JSON.parse(line.slice(6));
            console.log(event.type, event.content);
        }
    }
}

این کد ساده، جریان SSE را می‌خواند و هر رویداد را در کنسول نشان می‌دهد.

۶. مثال واقعی و کاربردی

پروژه کوچک: ربات پشتیبانی فروشگاه

می‌خواهیم یک ربات ساده بسازیم که به سوالات مشتریان جواب بدهد.

گام ۱: ساخت ایجنت پشتیبان

public class SupportAgent
{
    private readonly IChatClient _chatClient;

    public SupportAgent(IChatClient chatClient)
    {
        _chatClient = chatClient;
    }

    public string Name => "SupportBot";
    public string Description => "ربات پشتیبانی فروشگاه";
    public string Instructions =>
        "تو یک پشتیبان فروشگاهی هستی. کوتاه، محترمانه و واضح جواب بده.";
}

گام ۲: ثبت ایجنت و endpoint

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<IChatClient>(sp =>
{
    var client = new OpenAIClient("YOUR_API_KEY");
    return client.AsChatClient("gpt-4o-mini");
});

builder.Services.AddSingleton<SupportAgent>();

var app = builder.Build();

app.MapAgent<SupportAgent>("/support-agent");

app.Run();

گام ۳: اتصال UI

حالا کافی است فرانت‌اند به /support-agent درخواست POST بدهد. UI باید جریان رویدادها را بخواند و پیام‌ها را نمایش دهد.

این دقیقاً همان الگویی است که در چت‌بات‌های واقعی استفاده می‌شود.

۷. مباحث پیشرفته

ابزارها و Function Calling

می‌توانی به ایجنت ابزار بدهی. مثلاً وقتی کاربر شماره سفارش را می‌فرستد، ایجنت وضعیت سفارش را از دیتابیس بخواند:

public class SupportAgent
{
    public string Name => "SupportBot";
    public string Instructions => "برای پیگیری سفارش از ابزار GetOrderStatus استفاده کن.";

    public string GetOrderStatus(string orderId)
    {
        // در واقعیت از دیتابیس بخوان
        return $"سفارش {orderId} در حال ارسال است.";
    }
}

در SDK رسمی، توابع عمومی می‌توانند به‌عنوان ابزار در اختیار مدل قرار بگیرند. مدل تصمیم می‌گیرد چه زمانی ابزار را صدا بزند.

جریان‌سازی کامل

برای تجربه کاربری بهتر، به‌جای اینکه صبر کنی تا کل پاسخ ساخته شود، از Streaming استفاده کن. SDK دات‌نت این کار را به‌صورت خودکار انجام می‌دهد.

مدیریت حالت

اگر ایجنت نیاز به حفظ اطلاعات کاربر در طول مکالمه دارد، آن را در سمت سرور نگه دار، نه در UI. این کار از ناهماهنگی بین پروتکل و رابط کاربری جلوگیری می‌کند.

۸. اشتباهات رایج

1. نصب نکردن پکیج درست
   فقط Microsoft.Agents.AI.AspNetCore را نصب نکن و فکر کنی همه چیز کامل است. بسته به مدل، ممکن است به پکیج OpenAI یا Azure هم نیاز داشته باشی.

2. استفاده از GET به‌جای POST
   بسیاری از endpointهای ایجنت نیاز به ارسال پیام‌ها در بدنه درخواست دارند. با GET معمولاً کار نمی‌کنند.

3. فراموش کردن RunFinished
   اگر UI فقط منتظر رویداد متنی باشد و به رویداد پایان توجه نکند، ممکن است دکمه ارسال برای همیشه غیرفعال بماند.

4. پردازش JSON به‌عنوان کل پاسخ
   خروجی AG-UI یک جریان است، نه یک JSON کامل. باید به‌صورت خط‌به‌خط خوانده شود.

5. گذاشتن API Key در کد
   هرگز کلید را مستقیم در Program.cs ننویس. از متغیرهای محیطی استفاده کن.

۹. بهترین روش‌ها (Best Practices)

• دستورالعمل‌ها را کوتاه نگه دار: هرچه Instructions خلاصه‌تر باشد، مدل بهتر عمل می‌کند.
• حتی‌الامکان از Streaming استفاده کن: کاربران انتظار پاسخ تدریجی دارند.
• ابزارها را به تکه‌های کوچک تقسیم کن: هر Tool فقط یک کار انجام دهد.
• خطاها را مدیریت کن: اگر مدل یا ابزار خطا داد، حتماً رویداد خطا را به UI بفرست.
• از CancellationToken استفاده کن: اگر کاربر صفحه را بست، اجرای ایجنت متوقف شود.
• قبل از اتصال به UI واقعی، با یک تست ساده endpoint را بررسی کن.

۱۰. منابع و ادامه مسیر

• مستندات رسمی Microsoft Agents for .NET
  در Microsoft Learn یا GitHub با نام dotnet/agents جستجو کن.

• پروتکل AG-UI
  مستندات رسمی در سایت ag-ui.com

• Microsoft.Extensions.AI
  برای آشنایی بیشتر با IChatClient و ابزارهای مدل زبانی.

• نمونه‌های آماده
  در ریپازیتوری رسمی دات‌نت، پروژه‌های نمونه برای چت‌بات، پشتیبان و ابزارهای مختلف وجود دارد.

با یادگیری این مفاهیم پایه، می‌تونی خیلی سریع یک رابط کاربری حرفه‌ای به ایجنت هوش مصنوعی خودت وصل کنی.