نواة دلالية إلى دليل ترحيل إطار عمل العامل

فوائد إطار عمل عامل Microsoft

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

تلخص الأقسام التالية الاختلافات الرئيسية بين نواة دلالية Agent Framework و Microsoft Agent Framework لمساعدتك على ترحيل التعليمات البرمجية الخاصة بك.

1. تحديثات مساحة الاسم

النواة الدلالية

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;

إطار عمل الوكيل

توجد مساحات أسماء إطار عمل العامل ضمن Microsoft.Agents.AI. يستخدم إطار عمل العامل رسالة الذكاء الاصطناعي الأساسية وأنواع المحتوى من Microsoft.Extensions.AI للاتصال بين المكونات.

using Microsoft.Extensions.AI;
using Microsoft.Agents.AI;

2. تبسيط إنشاء العامل

النواة الدلالية

يعتمد كل عامل في نواة دلالية على مثيل Kernel ولديه فارغ Kernel إذا لم يتم توفيره.

 Kernel kernel = Kernel
    .AddOpenAIChatClient(modelId, apiKey)
    .Build();

 ChatCompletionAgent agent = new() { Instructions = ParrotInstructions, Kernel = kernel };

يتطلب Microsoft Foundry إنشاء مورد عامل في السحابة قبل إنشاء فئة عامل محلي تستخدمه.

PersistentAgentsClient azureAgentClient = AzureAIAgent.CreateAgentsClient(azureEndpoint, new DefaultAzureCredential());

PersistentAgent definition = await azureAgentClient.Administration.CreateAgentAsync(
    deploymentName,
    instructions: ParrotInstructions);

AzureAIAgent agent = new(definition, azureAgentClient);

تحذير

DefaultAzureCredential مناسب للتنمية ولكنه يتطلب دراسة متأنية في الإنتاج. في الإنتاج، ضع في اعتبارك استخدام بيانات اعتماد محددة (على سبيل المثال، ManagedIdentityCredential) لتجنب مشكلات زمن الانتقال، وبحث بيانات الاعتماد غير المقصودة، والمخاطر الأمنية المحتملة من الآليات الاحتياطية.

إطار عمل الوكيل

يتم تبسيط إنشاء العامل في إطار عمل العامل مع الملحقات التي يوفرها جميع الموفرين الرئيسيين.

AIAgent openAIAgent = chatClient.AsAIAgent(instructions: ParrotInstructions);
AIAgent azureFoundryAgent = aiProjectClient.AsAIAgent(model: deploymentName, instructions: ParrotInstructions);
AIAgent openAIAssistantAgent = await assistantClient.CreateAIAgentAsync(instructions: ParrotInstructions);

بالإضافة إلى ذلك، بالنسبة لموفري الوكلاء المستضافين، يمكنك أيضا استخدام AsAIAgent الأسلوب لاسترداد عامل من سجل عامل مستضاف موجود.

ProjectsAgentRecord agentRecord = await aiProjectClient.AgentAdministrationClient.GetAgentAsync(agentName);
AIAgent azureFoundryAgent = aiProjectClient.AsAIAgent(agentRecord);

3. إنشاء مؤشر ترابط/جلسة عمل العامل

النواة الدلالية

يجب على المتصل معرفة نوع مؤشر الترابط وإنشاءه يدويا.

// Create a thread for the agent conversation.
AgentThread thread = new OpenAIAssistantAgentThread(this.AssistantClient);
AgentThread thread = new AzureAIAgentThread(this.Client);
AgentThread thread = new OpenAIResponseAgentThread(this.Client);

إطار عمل الوكيل

العامل مسؤول عن إنشاء جلسة العمل.

// New.
AgentSession session = await agent.CreateSessionAsync();

4. تصفية مؤشر ترابط/جلسة عمل العامل المستضاف

تنطبق هذه الحالة حصريا على عدد قليل من موفري الذكاء الاصطناعي الذين لا يزالون يقدمون مؤشرات ترابط مستضافة.

النواة الدلالية

تحتوي مؤشرات الترابط على self أسلوب حذف.

موفر مساعدي OpenAI:

await thread.DeleteAsync();

إطار عمل الوكيل

Note

قدمت استجابات OpenAI نموذجا جديدا للمحادثة يبسط كيفية التعامل مع المحادثات. يبسط هذا التغيير إدارة محفوظات الدردشة المستضافة مقارنة بنموذج مساعدي OpenAI المهمل الآن. لمزيد من المعلومات، راجع دليل ترحيل مساعدي OpenAI.

لا يحتوي إطار عمل العامل على محفوظات دردشة أو واجهة برمجة تطبيقات لحذف جلسة العمل في AgentSession النوع حيث لا يدعم جميع الموفرين محفوظات الدردشة المستضافة أو حذف محفوظات الدردشة.

إذا كنت تحتاج إلى حذف محفوظات الدردشة ويسمح الموفر بذلك، يجب على المتصل تعقب الجلسات التي تم إنشاؤها وحذف hsitory الدردشة المقترنة به لاحقا عند الضرورة عبر SDK الخاص بالموفر.

موفر مساعدي OpenAI:

await assistantClient.DeleteThreadAsync(session.ConversationId);

5. تسجيل الأداة

النواة الدلالية

لعرض دالة كأداة، يجب عليك:

1. قم بتزيين الدالة بسمة [KernelFunction] .
2. Plugin لديك فئة أو استخدم KernelPluginFactory لالتفاف الدالة.
3. Kernel لديك لإضافة المكون الإضافي الخاص بك إلى.
4. Kernel مرر إلى العامل.

KernelFunction function = KernelFunctionFactory.CreateFromMethod(GetWeather);
KernelPlugin plugin = KernelPluginFactory.CreateFromFunctions("KernelPluginName", [function]);
Kernel kernel = ... // Create kernel
kernel.Plugins.Add(plugin);

ChatCompletionAgent agent = new() { Kernel = kernel, ... };

إطار عمل الوكيل

في إطار عمل العامل، في مكالمة واحدة يمكنك تسجيل الأدوات مباشرة في عملية إنشاء العامل.

AIAgent agent = chatClient.AsAIAgent(tools: [AIFunctionFactory.Create(GetWeather)]);

6. استدعاء العامل غير المتدفق

يمكن رؤية الاختلافات الرئيسية في أسماء الأساليب من Invoke إلى Runأنواع الإرجاع والمعلمات AgentRunOptions.

النواة الدلالية

يستخدم Non-Streaming نمط IAsyncEnumerable<AgentResponseItem<ChatMessageContent>> تدفق لإرجاع رسائل عامل متعددة.

await foreach (AgentResponseItem<ChatMessageContent> result in agent.InvokeAsync(userInput, thread, agentOptions))
{
    Console.WriteLine(result.Message);
}

إطار عمل الوكيل

يقوم Non-Streaming بإرجاع واحد AgentResponse مع استجابة العامل التي يمكن أن تحتوي على رسائل متعددة. تتوفر نتيجة النص للتشغيل في AgentResponse.Text أو AgentResponse.ToString(). يتم إرجاع كافة الرسائل التي تم إنشاؤها كجزء من الاستجابة في AgentResponse.Messages القائمة. قد يتضمن ذلك رسائل استدعاء الأداة ونتائج الوظائف وتحديثات المنطق والنتائج النهائية.

AgentResponse agentResponse = await agent.RunAsync(userInput, session);

7. استدعاء تدفق العامل

الاختلافات الرئيسية هي في أسماء الأسلوب من Invoke إلى Runأنواع الإرجاع والمعلمات AgentRunOptions.

النواة الدلالية

await foreach (StreamingChatMessageContent update in agent.InvokeStreamingAsync(userInput, thread))
{
    Console.Write(update);
}

إطار عمل الوكيل

يحتوي إطار عمل العامل على نمط واجهة برمجة تطبيقات دفق مماثل، مع الاختلاف الرئيسي هو أنه يقوم بإرجاع AgentResponseUpdate الكائنات التي تتضمن المزيد من المعلومات المتعلقة بالعامل لكل تحديث.

يتم إرجاع جميع التحديثات التي تنتجها أي خدمة تستند إلى AIAgent. تتوفر النتيجة النصية للعامل عن طريق تسلسل AgentResponse.Text القيم.

await foreach (AgentResponseUpdate update in agent.RunStreamingAsync(userInput, session))
{
    Console.Write(update); // Update is ToString() friendly
}

8. تواقيع دالة الأداة

المشكلة: تحتاج أساليب المكون الإضافي نواة دلالية إلى [KernelFunction] سمات.

public class MenuPlugin
{
    [KernelFunction] // Required.
    public static MenuItem[] GetMenu() => ...;
}

الحل: يمكن ل Agent Framework استخدام الأساليب مباشرة دون سمات.

public class MenuTools
{
    [Description("Get menu items")] // Optional description.
    public static MenuItem[] GetMenu() => ...;
}

9. تكوين الخيارات

المشكلة: إعداد الخيارات المعقدة في نواة دلالية.

OpenAIPromptExecutionSettings settings = new() { MaxTokens = 1000 };
AgentInvokeOptions options = new() { KernelArguments = new(settings) };

الحل: خيارات مبسطة في إطار عمل العامل.

ChatClientAgentRunOptions options = new(new() { MaxOutputTokens = 1000 });

Important

يوضح هذا المثال تمرير الخيارات الخاصة بالتنفيذ إلى ChatClientAgent. ليس كل AIAgents الدعم ChatClientAgentRunOptions. ChatClientAgent يتم توفيرها لبناء وكلاء استنادا إلى خدمات الاستدلال الأساسية، وبالتالي يدعم خيارات الاستدلال مثل MaxOutputTokens.

10. حقن التبعية

النواة الدلالية

Kernel التسجيل مطلوب في حاوية الخدمة لتكون قادرة على إنشاء عامل، حيث يحتاج كل تجريد عامل إلى تهيئة بخاصيةKernel.

يستخدم Agent نواة دلالية النوع كفئة تجريد أساسية للوكلاء.

services.AddKernel().AddProvider(...);
serviceContainer.AddKeyedSingleton<SemanticKernel.Agents.Agent>(
    TutorName,
    (sp, key) =>
        new ChatCompletionAgent()
        {
            // Passing the kernel is required.
            Kernel = sp.GetRequiredService<Kernel>(),
        });

إطار عمل الوكيل

يوفر AIAgent إطار عمل العامل النوع كفئة تجريد أساسية.

services.AddKeyedSingleton<AIAgent>(() => client.AsAIAgent(...));

11. دمج نوع العامل

النواة الدلالية

يوفر نواة دلالية فئات وكيل محددة لخدمات مختلفة، على سبيل المثال:

• ChatCompletionAgent للاستخدام مع خدمات الاستدلال المستندة إلى إكمال الدردشة.
• OpenAIAssistantAgent للاستخدام مع خدمة OpenAI Assistants.
• AzureAIAgent للاستخدام مع Foundry Agent Service.

إطار عمل الوكيل

يدعم إطار عمل العامل جميع الخدمات المذكورة عبر نوع وكيل واحد، ChatClientAgent.

ChatClientAgent يمكن استخدامها لإنشاء عوامل باستخدام أي خدمة أساسية توفر SDK التي تنفذ الواجهة IChatClient .

الاختلافات الرئيسية

فيما يلي ملخص للاختلافات الرئيسية بين إطار عمل عامل نواة دلالية وإطار عمل عامل Microsoft لمساعدتك على ترحيل التعليمات البرمجية الخاصة بك.

1. حزمة واستيراد التحديثات

النواة الدلالية

يتم تثبيت نواة دلالية الحزم كما semantic-kernel واستيرادها ك semantic_kernel. تحتوي الحزمة أيضا على عدد من extras التي يمكنك تثبيتها لتثبيت التبعيات المختلفة لموفري الذكاء الاصطناعي المختلفين والميزات الأخرى.

from semantic_kernel import Kernel
from semantic_kernel.agents import ChatCompletionAgent

إطار عمل الوكيل

يتم تثبيت حزمة إطار عمل العامل على أنها agent-framework واستيرادها ك agent_framework. تم إنشاء إطار عمل العامل بشكل مختلف، ويحتوي على حزمة agent-framework-core أساسية تحتوي على الوظيفة الأساسية، ثم هناك حزم متعددة تعتمد على تلك الحزمة الأساسية، مثل agent-framework-openaiو agent-framework-foundryو agent-framework-mem0agent-framework-copilotstudioو وما إلى ذلك. عند تشغيلهpip install agent-framework، سيتم تثبيت الحزمة الأساسية وحزم الموفر التي يتم شحنها في حزمة التعريف، بحيث يمكنك البدء بالميزات الشائعة بسرعة. عندما تكون مستعدا لتقليل عدد الحزم لأنك تعرف ما تحتاجه، يمكنك تثبيت الحزم التي تحتاج إليها فقط، لذلك على سبيل المثال إذا كنت تخطط فقط لاستخدام Foundry وMem0، يمكنك تثبيت هاتين الحزمتين فقط: pip install --pre agent-framework-foundry agent-framework-mem0، agent-framework-core وهي تبعية لهذين الاثنين، لذلك سيتم تثبيتهما تلقائيا.

على الرغم من تقسيم الحزم، فإن عمليات الاستيراد كلها من agent_framework، أو من وحدات نمطية. لذلك على سبيل المثال لاستيراد العميل ل Foundry يمكنك القيام به:

from agent_framework.foundry import FoundryChatClient

يتم استيراد العديد من الأنواع الأكثر استخداما مباشرة من agent_framework:

from agent_framework import Message, Agent

2. دمج نوع العامل

النواة الدلالية

يوفر نواة دلالية فئات وكيل محددة لخدمات مختلفة، على سبيل المثال، ChatCompletionAgent وAzureAIAgent وOpenAIAssistantAgent وما إلى ذلك. راجع أنواع العوامل في نواة دلالية.

إطار عمل الوكيل

في إطار عمل العامل، يتم بناء غالبية العوامل باستخدام Agent التي يمكن استخدامها مع جميع ChatClient الخدمات المستندة، مثل Foundry وOpenAI ChatCompletion واستجابات OpenAI. هناك عاملان إضافيان: CopilotStudioAgent للاستخدام مع Copilot Studio وللاستخدام A2AAgent مع A2A.

تستند جميع العوامل المضمنة إلى BaseAgent (from agent_framework import BaseAgent). وجميع العوامل متسقة مع الواجهة SupportsAgentRun (from agent_framework import SupportsAgentRun).

3. تبسيط إنشاء العامل

النواة الدلالية

يعتمد كل عامل في نواة دلالية على مثيل Kernel وسيكون فارغا Kernel إذا لم يتم توفيره.

from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion

agent = ChatCompletionAgent(
    service=OpenAIChatCompletion(),
    name="Support",
    instructions="Answer in one sentence.",
)

إطار عمل الوكيل

يمكن إنشاء العامل في إطار عمل العامل بطريقتين، مباشرة:

from agent_framework import Agent, Message
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

agent = Agent(client=FoundryChatClient(credential=AzureCliCredential()), instructions="You are a helpful assistant")

أو، مع أساليب الراحة التي يوفرها عملاء الدردشة:

from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

agent = FoundryChatClient(credential=AzureCliCredential()).as_agent(instructions="You are a helpful assistant")

يعرض الأسلوب المباشر جميع المعلمات الممكنة التي يمكنك تعيينها لعاملك. بينما يحتوي أسلوب الراحة على مجموعة فرعية، لا يزال بإمكانك تمرير نفس مجموعة المعلمات، لأنه يستدعي الأسلوب المباشر داخليا.

4. إنشاء مؤشر ترابط العامل

النواة الدلالية

يجب على المتصل معرفة نوع مؤشر الترابط وإنشاءه يدويا.

from semantic_kernel.agents import ChatHistoryAgentThread

thread = ChatHistoryAgentThread()

إطار عمل الوكيل

يمكن أن يطلب من العامل إنشاء مؤشر ترابط جديد لك.

agent = ...
session = agent.create_session()

يمكن أن تكون الجلسة محلية أو مدعومة بالخدمة اعتمادا على العامل/العميل وخيارات التشغيل:

1. استخدم agent.create_session() لجلسة عمل محلية جديدة.
2. استخدم agent.get_session(service_session_id=...) عند متابعة محادثة مدارة بواسطة الخدمة.
3. مرر جلسة العمل مع session=session إلى agent.run(...).

إطار عمل الوكيل

Note

قدمت استجابات OpenAI نموذجا جديدا للمحادثة يبسط كيفية التعامل مع المحادثات. هذا يبسط إدارة مؤشر الترابط المستضاف مقارنة بنموذج مساعدي OpenAI المهمل الآن. لمزيد من المعلومات، راجع دليل ترحيل مساعدي OpenAI.

لا يحتوي إطار عمل العامل على واجهة برمجة تطبيقات حذف مؤشر ترابط في AgentThread النوع حيث لا يدعم جميع الموفرين مؤشرات الترابط المستضافة أو حذف مؤشر الترابط وسيصبح هذا أكثر شيوعا مع انتقال المزيد من الموفرين إلى البنيات المستندة إلى الاستجابات.

إذا كنت تحتاج إلى حذف مؤشر الترابط ويسمح الموفر بذلك، يجب على المتصل تعقب مؤشرات الترابط التي تم إنشاؤها وحذفها لاحقا عند الضرورة عبر sdk للموفر.

موفر مساعدي OpenAI:

# OpenAI Assistants threads have self-deletion method in Semantic Kernel
await thread.delete_async()

5. تسجيل الأداة

النواة الدلالية

لعرض دالة كأداة، يجب عليك:

1. قم بتزيين الدالة باستخدام @kernel_function مصمم.
2. Plugin لديك فئة أو استخدم مصنع المكون الإضافي kernel لالتفاف الوظيفة.
3. Kernel لديك لإضافة المكون الإضافي الخاص بك إلى.
4. Kernel مرر إلى العامل.

from semantic_kernel.functions import kernel_function

class SpecialsPlugin:
    @kernel_function(name="specials", description="List daily specials")
    def specials(self) -> str:
        return "Clam chowder, Cobb salad, Chai tea"

agent = ChatCompletionAgent(
    service=OpenAIChatCompletion(),
    name="Host",
    instructions="Answer menu questions accurately.",
    plugins=[SpecialsPlugin()],
)

إطار عمل الوكيل

في مكالمة واحدة، يمكنك تسجيل الأدوات مباشرة في عملية إنشاء العامل. لا يحتوي إطار عمل العامل على مفهوم المكون الإضافي لتضمين وظائف متعددة، ولكن لا يزال بإمكانك القيام بذلك إذا رغبت في ذلك.

أبسط طريقة لإنشاء أداة هي فقط إنشاء وظيفة Python:

def get_weather(location: str) -> str:
    """Get the weather for a given location."""
    return f"The weather in {location} is sunny."

agent = chat_client.as_agent(tools=get_weather)

Note

المعلمة tools موجودة على كل من إنشاء العامل والأسلوب run (مع أو بدون stream=True)، بالإضافة get_response(..., options={"tools": [...]})إلى .

سيصبح اسم الدالة بعد ذلك اسم الأداة، وسيصبح docstring هو وصف الأداة، ويمكنك أيضا إضافة وصف إلى المعلمات:

from typing import Annotated

def get_weather(location: Annotated[str, "The location to get the weather for."]) -> str:
    """Get the weather for a given location."""
    return f"The weather in {location} is sunny."

وأخيرا، يمكنك استخدام مصمم الديكور لتخصيص اسم الأداة ووصفها بشكل أكبر:

from typing import Annotated
from agent_framework import tool

@tool(name="weather_tool", description="Retrieves weather information for any location")
def get_weather(location: Annotated[str, "The location to get the weather for."]):
    """Get the weather for a given location."""
    return f"The weather in {location} is sunny."

يعمل هذا أيضا عند إنشاء فئة بأدوات متعددة كأساليب.

عند إنشاء العامل، يمكنك الآن توفير أداة الوظيفة للعامل عن طريق تمريرها إلى المعلمة tools .

class Plugin:

    def __init__(self, initial_state: str):
        self.state: list[str] = [initial_state]

    def get_weather(self, location: Annotated[str, "The location to get the weather for."]) -> str:
        """Get the weather for a given location."""
        self.state.append(f"Requested weather for {location}. ")
        return f"The weather in {location} is sunny."

    def get_weather_details(self, location: Annotated[str, "The location to get the weather details for."]) -> str:
        """Get detailed weather for a given location."""
        self.state.append(f"Requested detailed weather for {location}. ")
        return f"The weather in {location} is sunny with a high of 25°C and a low of 15°C."

plugin = Plugin("Initial state")
agent = chat_client.as_agent(tools=[plugin.get_weather, plugin.get_weather_details])

... # use the agent

print("Plugin state:", plugin.state)

Note

يمكن أيضا تزيين @tool الوظائف داخل الفئة لتخصيص اسم ووصف الأدوات.

هذه الآلية مفيدة أيضا للأدوات التي تحتاج إلى إدخال إضافي لا يمكن توفيره من قبل LLM، مثل الاتصالات والأسرار وما إلى ذلك.

التوافق: استخدام KernelFunction كأدوات إطار عمل العامل

إذا كان لديك رمز نواة دلالية موجود مع KernelFunction مثيلات (إما من المطالبات أو من الأساليب)، يمكنك تحويلها إلى أدوات إطار عمل العامل باستخدام .as_agent_framework_tool الأسلوب .

Important

تتطلب هذه الميزة semantic-kernel الإصدار 1.38 أو أعلى.

استخدام KernelFunction من قالب موجه

from semantic_kernel import Kernel
from semantic_kernel.functions import KernelFunctionFromPrompt
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion, OpenAIChatPromptExecutionSettings
from semantic_kernel.prompt_template import KernelPromptTemplate, PromptTemplateConfig
from agent_framework.openai import OpenAIChatClient

# Create a kernel with services and plugins
kernel = Kernel()
# will get the api_key and model from the environment
kernel.add_service(OpenAIChatCompletion(service_id="default"))

# Create a function from a prompt template that uses plugin functions
function_definition = """
Today is: {{time.date}}
Current time is: {{time.time}}

Answer to the following questions using JSON syntax, including the data used.
Is it morning, afternoon, evening, or night (morning/afternoon/evening/night)?
Is it weekend time (weekend/not weekend)?
"""

prompt_template_config = PromptTemplateConfig(template=function_definition)
prompt_template = KernelPromptTemplate(prompt_template_config=prompt_template_config)

# Create a KernelFunction from the prompt
kernel_function = KernelFunctionFromPrompt(
    description="Determine the kind of day based on the current time and date.",
    plugin_name="TimePlugin",
    prompt_execution_settings=OpenAIChatPromptExecutionSettings(service_id="default", max_tokens=100),
    function_name="kind_of_day",
    prompt_template=prompt_template,
)

# Convert the KernelFunction to an Agent Framework tool
agent_tool = kernel_function.as_agent_framework_tool(kernel=kernel)

# Use the tool with an Agent Framework agent
agent = OpenAIChatClient(model="gpt-4o").as_agent(tools=agent_tool)
response = await agent.run("What kind of day is it?")
print(response.text)

استخدام KernelFunction من أسلوب

from semantic_kernel.functions import kernel_function
from agent_framework.openai import OpenAIChatClient

# Create a plugin class with kernel functions
@kernel_function(name="get_weather", description="Get the weather for a location")
def get_weather(self, location: str) -> str:
    return f"The weather in {location} is sunny."

# Get the KernelFunction and convert it to an Agent Framework tool
agent_tool = get_weather.as_agent_framework_tool()

# Use the tool with an Agent Framework agent
agent = OpenAIChatClient(model="gpt-4o").as_agent(tools=agent_tool)
response = await agent.run("What's the weather in Seattle?")
print(response.text)

استخدام VectorStore مع create_search_function

يمكنك أيضا استخدام تكاملات VectorStore نواة دلالية مع إطار عمل العامل. create_search_function يرجع الأسلوب من مجموعة مخزن متجهات KernelFunction التي يمكن تحويلها إلى أداة إطار عمل العامل.

from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.open_ai import OpenAITextEmbedding
from semantic_kernel.connectors.azure_ai_search import AzureAISearchCollection
from semantic_kernel.functions import KernelParameterMetadata
from agent_framework.openai import OpenAIChatClient

# Define your data model
class HotelSampleClass:
    HotelId: str
    HotelName: str
    Description: str
    # ... other fields

# Create an Azure AI Search collection
collection = AzureAISearchCollection[str, HotelSampleClass](
    record_type=HotelSampleClass,
    embedding_generator=OpenAITextEmbedding()
)

async with collection:
    await collection.ensure_collection_exists()
    # Load your records into the collection
    # await collection.upsert(records)

    # Create a search function from the collection
    search_function = collection.create_search_function(
        description="A hotel search engine, allows searching for hotels in specific cities.",
        search_type="keyword_hybrid",
        filter=lambda x: x.Address.Country == "USA",
        parameters=[
            KernelParameterMetadata(
                name="query",
                description="What to search for.",
                type="str",
                is_required=True,
                type_object=str,
            ),
            KernelParameterMetadata(
                name="city",
                description="The city that you want to search for a hotel in.",
                type="str",
                type_object=str,
            ),
            KernelParameterMetadata(
                name="top",
                description="Number of results to return.",
                type="int",
                default_value=5,
                type_object=int,
            ),
        ],
        string_mapper=lambda x: f"(hotel_id: {x.record.HotelId}) {x.record.HotelName} - {x.record.Description}",
    )

    # Convert the search function to an Agent Framework tool
    search_tool = search_function.as_agent_framework_tool()

    # Use the tool with an Agent Framework agent
    agent = OpenAIChatClient(model="gpt-4o").as_agent(
        instructions="You are a travel agent that helps people find hotels.",
        tools=search_tool
    )
    response = await agent.run("Find me a hotel in Seattle")
    print(response.text)

يعمل هذا النمط مع أي موصل نواة دلالية VectorStore (البحث باستخدام الذكاء الاصطناعي في Azure وQdrant و Pinecone وما إلى ذلك)، مما يسمح لك بالاستفادة من البنية الأساسية الحالية للبحث عن المتجهات باستخدام عوامل Agent Framework.

تسمح لك طبقة التوافق هذه بترحيل التعليمات البرمجية الخاصة بك تدريجيا من نواة دلالية إلى إطار عمل العامل، وإعادة استخدام تطبيقاتك الحالية KernelFunction مع الاستفادة من أنماط إنشاء العامل المبسطة وتنفيذها في إطار عمل العامل.

6. استدعاء العامل غير المتدفق

يمكن رؤية الاختلافات الرئيسية في أسماء الأساليب من invoke إلى run، وأنواع الإرجاع (على سبيل المثال، AgentResponse) والمعلمات.

النواة الدلالية

يستخدم استدعاء Non-Streaming نمط مكرر غير متزامن لإرجاع رسائل عامل متعددة.

async for response in agent.invoke(
    messages=user_input,
    thread=thread,
):
    print(f"# {response.role}: {response}")
    thread = response.thread

وكانت هناك طريقة ملائمة للحصول على الاستجابة النهائية:

response = await agent.get_response(messages="How do I reset my bike tire?", thread=thread)
print(f"# {response.role}: {response}")

إطار عمل الوكيل

يقوم تشغيل Non-Streaming بإرجاع واحد AgentResponse مع استجابة العامل التي يمكن أن تحتوي على رسائل متعددة. تتوفر نتيجة النص للتشغيل في response.text أو str(response). يتم إرجاع كافة الرسائل التي تم إنشاؤها كجزء من الاستجابة في response.messages القائمة. قد يتضمن ذلك رسائل استدعاء الأداة ونتائج الوظائف وتحديثات المنطق والنتائج النهائية.

agent = ...

response = await agent.run(user_input, session=session)
print("Agent response:", response.text)

7. استدعاء تدفق العامل

الاختلافات الرئيسية في أسماء الأساليب من invoke إلى run(..., stream=True)، وأنواع الإرجاع (AgentResponseUpdate) والمعلمات.

النواة الدلالية

async for update in agent.invoke_stream(
    messages="Draft a 2 sentence blurb.",
    thread=thread,
):
    if update.message:
        print(update.message.content, end="", flush=True)

إطار عمل الوكيل

نمط واجهة برمجة تطبيقات دفق مماثل مع الاختلاف الرئيسي هو أنه يقوم بإرجاع AgentResponseUpdate العناصر بما في ذلك المزيد من المعلومات المتعلقة بالعامل لكل تحديث.

يتم إرجاع جميع المحتويات التي تنتجها أي خدمة أساسية للعامل. تتوفر النتيجة النهائية للعامل عن طريق دمج القيم في update استجابة واحدة.

from agent_framework import AgentResponse
agent = ...
updates = []
stream = agent.run(user_input, session=session, stream=True)
async for update in stream:
    updates.append(update)
    print(update.text)

full_response = AgentResponse.from_updates(updates)
print("Full agent response:", full_response.text)

يمكنك حتى القيام بذلك مباشرة:

from agent_framework import AgentResponse
agent = ...
full_response = await AgentResponse.from_update_generator(agent.run(user_input, session=session, stream=True))
print("Full agent response:", full_response.text)

8. تكوين الخيارات

المشكلة: إعداد الخيارات المعقدة في نواة دلالية

from semantic_kernel.connectors.ai.open_ai import OpenAIPromptExecutionSettings

settings = OpenAIPromptExecutionSettings(max_tokens=1000)
arguments = KernelArguments(settings)

response = await agent.get_response(user_input, thread=thread, arguments=arguments)

الحل: خيارات مبسطة تستند إلى TypedDict في إطار عمل العامل

يستخدم إطار عمل العامل نظام خيارات يستند إلى TypedDict ل ChatClients و Agents. يتم تمرير الخيارات عبر معلمة واحدة options كقاموس مكتوب، مع فئات TypedDict الخاصة بالموفر (مثل OpenAIChatOptions) للإكمال التلقائي الكامل ل IDE والتحقق من النوع.

from agent_framework.openai import OpenAIChatClient

client = OpenAIChatClient()

# Set default options at agent creation
agent = client.as_agent(
    instructions="You are a helpful assistant.",
    default_options={
        "max_tokens": 1000,
        "temperature": 0.7,
    }
)

# Override options per call
response = await agent.run(
    user_input,
    thread,
    options={
        "max_tokens": 500,
        "frequency_penalty": 0.5,
    }
)

Note

tools تظل المعلمات و instructions كوسيطات كلمات أساسية مباشرة حول إنشاء العامل وأساليبهrun()، ولا يتم تمريرها عبر options القاموس. راجع دليل ترقية الخيارات التي تم كتابتها للحصول على أنماط ترحيل مفصلة.

Note

سيتوفر الدعم لهذه الميزة قريبا. راجع مستودع Agent Framework Go للحصول على أحدث حالة.

الخطوات التالية

دليل التشغيل السريع