Microsoft Agent Framework لإنقاذ عيد الميلاد

· 11 دقيقة قراءة

مقدمة

قد يكون العثور على هدايا عيد الميلاد المثالية أمرًا مرهقًا. بين تبادل الأفكار حول أفكار الهدايا، ومقارنة الأسعار عبر المتاجر، والتأكد من وصول كل شيء في الوقت المحدد، سرعان ما يصبح التسوق أثناء العطلات أمرًا مرهقًا. ماذا لو تمكنا من تفويض هذه المهام إلى عملاء الذكاء الاصطناعي المتخصصين الذين يعملون معًا؟ في هذا المنشور، سنستكشف كيفية استخدام Microsoft Agent Framework لبناء نظام متعدد الوكلاء حيث يتخصص كل وكيل في مهمة محددة، بدءًا من إنشاء أفكار الهدايا وحتى مقارنة الأسعار، ويتم تنسيق كل ذلك من خلال سير العمل.

التقويم التقني الاحتفالي لعام 2025

يعد هذا المشروع جزءًا من جلستي في Festive Tech Calendar 2025، وهو حدث مجتمعي رائع يحتفل بالتكنولوجيا خلال موسم العطلات. يمكنك العثور على المزيد حول الحدث على Sessionize.

ما هو إطار عمل وكيل Microsoft؟

Agent Framework هو حل Microsoft لبناء وتنسيق ونشر وكلاء الذكاء الاصطناعي والأنظمة متعددة الوكلاء. فهو يوفر أساسًا مرنًا لإنشاء الوكلاء الذين يمكنهم العمل بشكل تسلسلي أو متزامن أو من خلال أنماط التسليم. يدعم إطار العمل نماذج OpenAI وAzure OpenAI وMicrosoft Foundry، مما يجعله متعدد الاستخدامات بشكل لا يصدق.

تشمل الميزات الرئيسية ما يلي:

  • تنسيق متعدد الوكلاء: الدردشة الجماعية، وأنماط التسلسل، والمتزامنة، والتسليم
  • نظام المكونات الإضافية: يمتد ليشمل الوظائف الأصلية وOpenAPI وبروتوكول السياق النموذجي (MCP)
  • دعم سير العمل: أنشئ مسارات وكيل معقدة باستخدام منفذين وحواف

المتطلبات الأساسية

قبل الغوص في الكود، تأكد من أن لديك:

-.نت 9

  • الوصول إلى Azure OpenAI (أو مفتاح OpenAI API)
  • Visual Studio أو Visual Studio Code

قم بتثبيت الحزم المطلوبة (لاحظ أن علامة --prerelease مطلوبة أثناء المعاينة):

dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
dotnet add package Microsoft.Agents.AI.Workflows --prerelease
dotnet add package Azure.AI.OpenAI
dotnet add package Azure.Identity
dotnet add package Azure.AI.Agents.Persistent --prerelease

وكلاء تسوق الهدايا

سيتكون مكتشف هدايا عيد الميلاد الخاص بنا من ثلاثة وكلاء متخصصين يعملون معًا:

  1. ** وكيل فكرة الهدية ** - يُنشئ اقتراحات هدايا إبداعية بناءً على الملف الشخصي للمستلم
  2. ** وكيل مقارنة الأسعار ** - يجد أفضل الأسعار عبر المتاجر المختلفة
  3. وكيل الملخص - يجمع التوصيات النهائية

النماذج

لنبدأ بتحديد نماذج البيانات التي ستتدفق عبر مسار الوكلاء:

public class GiftRecipient
{
    public string Name { get; set; } = string.Empty;
    public int Age { get; set; }
    public List<string> Interests { get; set; } = [];
    public decimal Budget { get; set; }
}

public class GiftIdea
{
    public string Name { get; set; } = string.Empty;
    public string Description { get; set; } = string.Empty;
    public string Category { get; set; } = string.Empty;
    public decimal EstimatedPrice { get; set; }
}

public class PriceResult
{
    public string GiftName { get; set; } = string.Empty;
    public string Store { get; set; } = string.Empty;
    public decimal Price { get; set; }
    public string Url { get; set; } = string.Empty;
}

public class GiftRecommendation
{
    public GiftIdea Gift { get; set; } = new();
    public List<PriceResult> Prices { get; set; } = [];
    public PriceResult? BestDeal { get; set; }
}

بناء الوكلاء

يكمن جمال Agent Framework في مدى سهولة إنشاء وكلاء متخصصين. كل وكيل هو ببساطة ChatClientAgent مع موجه نظام محدد يحدد خبرته.

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Workflows;
using Microsoft.Extensions.AI;

public static class ChristmasAgentFactory
{
    public static AIAgent CreateGiftIdeaAgent(IChatClient chatClient)
    {
        return new ChatClientAgent(
            chatClient,
            @"You are a creative Christmas gift advisor. When given information about a person 
            (age, interests, budget), you suggest thoughtful and personalized gift ideas.
            
            For each suggestion, provide:
            - Gift name
            - Brief description of why it's a good fit
            - Category (Electronics, Books, Fashion, Home, Experience, etc.)
            - Estimated price range
            
            Always suggest 3-5 gift options within the specified budget.
            Format your response as a structured list.");
    }

    public static AIAgent CreatePriceComparisonAgent(IChatClient chatClient)
    {
        return new ChatClientAgent(
            chatClient,
            @"You are a price comparison specialist. Given a list of gift ideas, 
            you research and compare prices from different online retailers.
            
            For each gift, provide:
            - Store name (Amazon, Best Buy, Target, Walmart, etc.)
            - Current price
            - Any available discounts or deals
            
            Always highlight the best deal for each item.
            Consider shipping costs and delivery times for Christmas.");
    }

    public static AIAgent CreateSummaryAgent(IChatClient chatClient)
    {
        return new ChatClientAgent(
            chatClient,
            @"You are a gift recommendation summarizer. Take the gift ideas and price 
            comparisons and create a final recommendation report.
            
            Your summary should:
            - Rank gifts by value (quality vs price)
            - Highlight the top pick with reasoning
            - Include total cost estimate
            - Add any tips for holiday shopping
            
            Make the summary cheerful and festive!");
    }
}

إنشاء سير العمل

والآن يأتي الجزء الممتع، وهو ربط وكلائنا بسير عمل متسلسل. يوفر إطار عمل الوكيل WorkflowBuilder وAgentWorkflowBuilder لتكوين الوكلاء في أنماط مختلفة.

public static class ChristmasGiftWorkflow
{
    public static async Task RunAsync()
    {
        // Set up the Azure OpenAI client
        var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") 
            ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
        var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") 
            ?? "gpt-4o-mini";
        
        var chatClient = new AzureOpenAIClient(
            new Uri(endpoint), 
            new DefaultAzureCredential())
            .GetChatClient(deploymentName)
            .AsIChatClient();

        // Create our specialized agents
        AIAgent giftIdeaAgent = ChristmasAgentFactory.CreateGiftIdeaAgent(chatClient);
        AIAgent priceAgent = ChristmasAgentFactory.CreatePriceComparisonAgent(chatClient);
        AIAgent summaryAgent = ChristmasAgentFactory.CreateSummaryAgent(chatClient);

        // Build a sequential workflow: Ideas -> Prices -> Summary
        var workflow = AgentWorkflowBuilder.BuildSequential(
            "ChristmasGiftFinder",
            [giftIdeaAgent, priceAgent, summaryAgent]);

        // Define our gift recipient
        var recipient = new GiftRecipient
        {
            Name = "Mom",
            Age = 55,
            Interests = ["gardening", "cooking", "reading", "yoga"],
            Budget = 100
        };

        var prompt = $@"Find Christmas gifts for {recipient.Name}, 
            age {recipient.Age}, who enjoys {string.Join(", ", recipient.Interests)}. 
            Budget: ${recipient.Budget}";

        // Execute the workflow with streaming
        await using StreamingRun run = await InProcessExecution.StreamAsync(
            workflow, 
            new ChatMessage(ChatRole.User, prompt));

        // Send the turn token to start processing
        await run.TrySendMessageAsync(new TurnToken(emitEvents: true));

        // Watch for workflow events
        await foreach (WorkflowEvent evt in run.WatchStreamAsync())
        {
            if (evt is AgentRunUpdateEvent agentUpdate)
            {
                Console.Write(agentUpdate.Data);
            }
            else if (evt is WorkflowOutputEvent outputEvent)
            {
                Console.WriteLine("\n🎄 Final Recommendations:");
                Console.WriteLine(outputEvent.Data);
            }
        }
    }
}

تشغيل الوكلاء بشكل متزامن

ماذا لو أردنا البحث عن هدايا لعدة أشخاص في وقت واحد؟ يدعم Agent Framework التنفيذ المتزامن، وهو مثالي لهذا السيناريو:

public static async Task FindGiftsForEveryoneAsync(IChatClient chatClient, List<GiftRecipient> recipients)
{
    // Create an agent for each recipient
    var agents = recipients.Select(r => new ChatClientAgent(
        chatClient,
        $@"Find the perfect Christmas gift for {r.Name} (age {r.Age}), 
           who loves {string.Join(", ", r.Interests)}. Budget: ${r.Budget}.
           Provide one well-researched recommendation with price."
    )).ToList();

    // Build a concurrent workflow - all agents run in parallel
    var workflow = AgentWorkflowBuilder.BuildConcurrent(
        "FamilyGiftFinder",
        agents);

    await using StreamingRun run = await InProcessExecution.StreamAsync(
        workflow, 
        new ChatMessage(ChatRole.User, "Find gifts now!"));

    await run.TrySendMessageAsync(new TurnToken(emitEvents: true));

    await foreach (WorkflowEvent evt in run.WatchStreamAsync())
    {
        if (evt is WorkflowOutputEvent output)
        {
            Console.WriteLine("🎁 All gift recommendations ready!");
            Console.WriteLine(output.Data);
        }
    }
}

منفذون مخصصون لمزيد من التحكمبالنسبة للسيناريوهات الأكثر تعقيدًا، يمكنك إنشاء برامج تنفيذية مخصصة تمنحك تحكمًا دقيقًا في سير العمل:

public sealed class GiftValidatorExecutor : Executor<List<ChatMessage>, List<ChatMessage>>
{
    public GiftValidatorExecutor() : base("GiftValidator") { }

    public override async ValueTask<List<ChatMessage>> HandleAsync(
        List<ChatMessage> messages,
        IWorkflowContext context,
        CancellationToken cancellationToken = default)
    {
        var lastMessage = messages.LastOrDefault()?.Text ?? "";
        
        // Validate that suggestions are within budget
        if (lastMessage.Contains("over budget", StringComparison.OrdinalIgnoreCase))
        {
            Console.WriteLine("⚠️ Some suggestions exceeded budget, filtering...");
            // Add validation logic here
        }

        Console.WriteLine("✅ Gift suggestions validated!");
        return messages;
    }
}

يمكنك بعد ذلك إدراج هذا المنفذ في سير العمل الخاص بك:

var validator = new GiftValidatorExecutor();

var workflow = new WorkflowBuilder(giftIdeaAgent)
    .AddEdge(giftIdeaAgent, validator)
    .AddEdge(validator, priceAgent)
    .AddEdge(priceAgent, summaryAgent)
    .WithOutputFrom(summaryAgent)
    .Build();

إضافة بحث ويب حقيقي باستخدام Bing Grounding

حتى الآن، يقوم وكلاؤنا بإنشاء استجابات بناءً على معرفة نموذج الذكاء الاصطناعي. ولكن ماذا لو أردنا البحث في الويب عن أسعار المنتجات الفعلية ومدى توفرها؟ هذا هو المكان الذي يأتي فيه التأريض باستخدام بحث Bing. إنها أداة متوفرة في Microsoft Foundry (المعروف سابقًا باسم Azure AI Foundry) والتي تسمح لعملائك بدمج بيانات الويب العامة في الوقت الفعلي عند إنشاء الاستجابات.

أولاً، ستحتاج إلى إنشاء مورد التأريض باستخدام بحث Bing في Azure Portal. تأكد من إنشائه في نفس مجموعة الموارد مثل مشروع الذكاء الاصطناعي الخاص بك.

إعداد التأريض باستخدام بحث Bing

إن جمال التأريض مع Bing Search هو أنه يتكامل مباشرة مع Azure AI Agents. يقرر الوكيل متى يستخدم أداة البحث بناءً على استعلام المستخدم، ويبحث في الويب، ويستخدم النتائج لإنشاء استجابة مرتكزة.

using Azure.AI.Agents.Persistent;
using Azure.Identity;

public static class BingGroundingSetup
{
    public static async Task<PersistentAgent> CreateAgentWithBingGroundingAsync(
        string projectEndpoint,
        string modelDeploymentName,
        string bingConnectionId)
    {
        // Create the Persistent Agents client
        var agentClient = new PersistentAgentsClient(projectEndpoint, new DefaultAzureCredential());

        // Configure the Bing Grounding tool
        var bingGroundingTool = new BingGroundingToolDefinition(
            new BingGroundingSearchToolParameters(
                [new BingGroundingSearchConfiguration(bingConnectionId)]
            )
        );

        // Create the agent with Bing Grounding enabled
        var agent = await agentClient.Administration.CreateAgentAsync(
            model: modelDeploymentName,
            name: "ChristmasPriceHunter",
            instructions: @"You are a Christmas gift price comparison specialist.
                
                When given gift ideas, use Bing to search for:
                - Current prices at major retailers (Amazon, Best Buy, Target, Walmart)
                - Available discounts and holiday deals
                - Shipping times to ensure delivery before Christmas
                
                Always provide URLs to the products you find.
                Highlight the best deals and recommend where to buy.",
            tools: [bingGroundingTool]
        );

        return agent;
    }
}

إنشاء وكيل لمقارنة الأسعار باستخدام بحث حقيقي

لنقم الآن بإنشاء وكيل كامل لمقارنة الأسعار يقوم بالبحث في الويب عن معلومات المنتج الحقيقية:

using Azure.AI.Agents.Persistent;
using Azure.Identity;

public class ChristmasPriceAgent
{
    private readonly PersistentAgentsClient _client;
    private readonly string _modelDeployment;
    private readonly string _bingConnectionId;

    public ChristmasPriceAgent(string projectEndpoint, string modelDeployment, string bingConnectionId)
    {
        _client = new PersistentAgentsClient(projectEndpoint, new DefaultAzureCredential());
        _modelDeployment = modelDeployment;
        _bingConnectionId = bingConnectionId;
    }

    public async Task<string> FindGiftPricesAsync(string giftIdeas)
    {
        // Create agent with Bing Grounding
        var bingTool = new BingGroundingToolDefinition(
            new BingGroundingSearchToolParameters(
                [new BingGroundingSearchConfiguration(_bingConnectionId)]
            )
        );

        var agent = await _client.Administration.CreateAgentAsync(
            model: _modelDeployment,
            name: "PriceHunter",
            instructions: @"Search the web for current prices on the given gift ideas. 
                For each gift, find prices from at least 2-3 different stores.
                Include direct links to the products.
                Note any Christmas sales or discounts available.",
            tools: [bingTool]
        );

        try
        {
            // Create a thread for the conversation
            var thread = await _client.Threads.CreateThreadAsync();

            // Add the gift ideas as a message
            await _client.Messages.CreateMessageAsync(
                thread.Id,
                MessageRole.User,
                $"Find current prices for these gift ideas: {giftIdeas}"
            );

            // Run the agent
            var run = await _client.Runs.CreateRunAsync(thread.Id, agent.Id);

            // Wait for completion
            do
            {
                await Task.Delay(500);
                run = await _client.Runs.GetRunAsync(thread.Id, run.Id);
            }
            while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress);

            // Get the response
            var messages = _client.Messages.GetMessages(thread.Id);
            var response = messages
                .Where(m => m.Role == MessageRole.Agent)
                .SelectMany(m => m.ContentItems)
                .OfType<MessageTextContent>()
                .FirstOrDefault();

            // Clean up
            await _client.Threads.DeleteThreadAsync(thread.Id);

            return response?.Text ?? "No results found.";
        }
        finally
        {
            // Clean up the agent
            await _client.Administration.DeleteAgentAsync(agent.Id);
        }
    }
}

دمج Bing Grounding في سير العمل

فيما يلي كيفية استخدام وكيل الأسعار المدعوم من Bing في سير عمل كامل للبحث عن الهدايا:

public static async Task RunWithBingGroundingAsync()
{
    var projectEndpoint = Environment.GetEnvironmentVariable("PROJECT_ENDPOINT")!;
    var modelDeployment = Environment.GetEnvironmentVariable("MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";
    var bingConnectionId = Environment.GetEnvironmentVariable("BING_CONNECTION_ID")!;
    // Connection ID format: /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}/connections/{connection}

    Console.WriteLine("🔍 Searching the web for real prices with Bing Grounding...\n");

    var priceAgent = new ChristmasPriceAgent(projectEndpoint, modelDeployment, bingConnectionId);

    // First, generate gift ideas (could come from another agent)
    var giftIdeas = "1. Milwaukee cordless drill set, 2. Weber portable grill, 3. Carhartt beanie";

    // Search for real prices
    var priceResults = await priceAgent.FindGiftPricesAsync(giftIdeas);

    Console.WriteLine("📊 Price Comparison Results:");
    Console.WriteLine(priceResults);
    Console.WriteLine("\n🎁 Happy Shopping! 🎁");
}

معالجة الاستشهادات من نتائج Bing

أحد الجوانب المهمة في التأريض باستخدام بحث Bing هو أن الردود تتضمن اقتباسات مع روابط إلى مواقع الويب المصدر. وإليك كيفية استخراجها وعرضها:

public static void ProcessBingGroundingResponse(IEnumerable<PersistentThreadMessage> messages)
{
    foreach (var message in messages.Where(m => m.Role == MessageRole.Agent))
    {
        foreach (var content in message.ContentItems)
        {
            if (content is MessageTextContent textContent)
            {
                var response = textContent.Text;

                // Process URL citations
                if (textContent.Annotations != null)
                {
                    foreach (var annotation in textContent.Annotations)
                    {
                        if (annotation is MessageTextUriCitationAnnotation uriAnnotation)
                        {
                            // Replace citation placeholder with markdown link
                            response = response.Replace(
                                uriAnnotation.Text,
                                $" [{uriAnnotation.UriCitation.Title}]({uriAnnotation.UriCitation.Uri})"
                            );
                        }
                    }
                }

                Console.WriteLine(response);
            }
        }
    }
}

الآن، عند تشغيل وكيل مقارنة الأسعار، فإنه يستخدم التأريض باستخدام بحث Bing للعثور على قوائم المنتجات الحقيقية والأسعار الحالية والصفقات المتاحة من الويب المباشر. يقرر الوكيل تلقائيًا متى يجب البحث بناءً على الاستعلام ويعيد الإجابات المؤرضة مع الاستشهادات المناسبة.

##البرنامج الكامل

إليك كيفية تجميع كل شيء معًا في Program.cs:

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Workflows;
using Microsoft.Extensions.AI;

Console.WriteLine("🎄 Christmas Gift Finder - Powered by AI Agents 🎄\n");

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!;
var deployment = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";

var chatClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
    .GetChatClient(deployment)
    .AsIChatClient();

// Create the agent team
var ideaAgent = ChristmasAgentFactory.CreateGiftIdeaAgent(chatClient);
var priceAgent = ChristmasAgentFactory.CreatePriceComparisonAgent(chatClient);
var summaryAgent = ChristmasAgentFactory.CreateSummaryAgent(chatClient);

// Build the workflow
var workflow = AgentWorkflowBuilder.BuildSequential(
    "ChristmasGiftWorkflow",
    [ideaAgent, priceAgent, summaryAgent]);

Console.Write("Who are you shopping for? ");
var recipientName = Console.ReadLine() ?? "Someone special";

Console.Write("What are their interests? ");
var interests = Console.ReadLine() ?? "general";

Console.Write("What's your budget? $");
var budget = Console.ReadLine() ?? "50";

var prompt = $"Find Christmas gifts for {recipientName} who enjoys {interests}. Budget: ${budget}";

Console.WriteLine("\n🔍 Searching for the perfect gifts...\n");

await using var run = await InProcessExecution.StreamAsync(
    workflow,
    new ChatMessage(ChatRole.User, prompt));

await run.TrySendMessageAsync(new TurnToken(emitEvents: true));

await foreach (var evt in run.WatchStreamAsync())
{
    switch (evt)
    {
        case AgentRunUpdateEvent update:
            Console.Write(update.Update.Text);
            break;
        case WorkflowOutputEvent output:
            Console.WriteLine("\n\n🎁 Happy Shopping! 🎁");
            break;
    }
}

الخلاصة

يجعل Microsoft Agent Framework من السهل بشكل مدهش إنشاء أنظمة متعددة الوكلاء حيث يتخصص كل وكيل في مهمة محددة. ومن خلال تنسيق هؤلاء الوكلاء من خلال سير العمل، يمكننا معالجة المشكلات المعقدة مثل التسوق في عيد الميلاد بطريقة منظمة وفعالة.

ما يجعل هذا أكثر قوة هو القدرة على إضافة إمكانات العالم الحقيقي من خلال الأدوات. من خلال دمج Grounding مع Bing Search من Microsoft Foundry، يستطيع وكيل مقارنة الأسعار لدينا البحث فعليًا في الويب عن الأسعار والصفقات الحالية ومدى التوفر - مما يحول روبوت الدردشة البسيط الذي يعمل بالذكاء الاصطناعي إلى مساعد تسوق مفيد حقًا مع الاستشهادات المناسبة.

إن دعم إطار العمل للأنماط التسلسلية والمتزامنة والتسليم يعني أنه يمكنك تصميم أنظمة الوكلاء التي تتوافق مع احتياجاتك الدقيقة. سواء كان الأمر يتعلق بالعثور على الهدايا، أو التخطيط للرحلات، أو أي مهمة أخرى متعددة الخطوات، فإن Agent Framework يوفر العناصر الأساسية لتحقيق ذلك.في موسم العطلات هذا، اسمح لعملاء الذكاء الاصطناعي بالتعامل مع البحث بينما تركز أنت على تغليف الهدايا والاستمتاع بالوقت مع العائلة!

كود المصدر

تستند المفاهيم الموضحة في هذا المنشور إلى عينات إطار عمل الوكيل الرسمية. يمكنك استكشاف المزيد من الأمثلة على مستودع Microsoft Agent Framework GitHub.

إجازة سعيدة وترميز سعيد! 🎄