Руководство по миграции семантического ядра в Agent Framework

В следующих разделах приведены основные различия между платформой агента семантического ядра и Microsoft Agent Framework, которые помогут вам перенести код.

1. Обновления пространства имен

Семантическое ядро

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

Платформа агента

Пространства имен Agent Framework находятся в разделе Microsoft.Agents.AI. Agent Framework использует основное сообщение ИИ и типы контента для 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 };

Azure AI Foundry требует, чтобы ресурс агента был создан в облаке перед созданием локального класса агента, использующего его.

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

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

AzureAIAgent agent = new(definition, azureAgentClient);

Платформа агента

Создание агента в Agent Framework упрощается с расширениями, предоставляемыми всеми основными поставщиками.

AIAgent openAIAgent = chatClient.CreateAIAgent(instructions: ParrotInstructions);
AIAgent azureFoundryAgent = await persistentAgentsClient.CreateAIAgentAsync(instructions: ParrotInstructions);
AIAgent openAIAssistantAgent = await assistantClient.CreateAIAgentAsync(instructions: ParrotInstructions);

Кроме того, для поставщиков размещенных агентов можно также использовать GetAIAgent метод для получения агента из существующего размещенного агента.

AIAgent azureFoundryAgent = await persistentAgentsClient.GetAIAgentAsync(agentId);

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.
AgentThread thread = agent.GetNewThread();

4. Очистка потока размещенного агента

Этот случай применяется исключительно к нескольким поставщикам ИИ, которые по-прежнему предоставляют размещенные потоки.

Семантическое ядро

Потоки имеют self метод удаления.

Поставщик помощников OpenAI:

await thread.DeleteAsync();

Платформа агента

У агента Framework нет API удаления потоков в типе AgentThread , так как не все поставщики поддерживают размещенные потоки или удаление потоков. Эта конструкция станет более распространенной, так как больше поставщиков переходят на архитектуры на основе ответов.

Если требуется удаление потоков и поставщик разрешает его, вызывающий объект должен отслеживать созданные потоки и удалять их позже с помощью пакета SDK поставщика.

Поставщик помощников OpenAI:

await assistantClient.DeleteThreadAsync(thread.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, ... };

Платформа агента

В Agent Framework в одном вызове можно зарегистрировать средства непосредственно в процессе создания агента.

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

6. Вызов без потоковой передачи агента

Ключевые различия можно увидеть в именах методов от InvokeRun, возвращаемых типов и параметров AgentRunOptions.

Семантическое ядро

Непотоковый использует шаблон IAsyncEnumerable<AgentResponseItem<ChatMessageContent>> потоковой передачи для возврата нескольких сообщений агента.

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

Платформа агента

Непотоковый возвращает один с AgentRunResponse ответом агента, который может содержать несколько сообщений. Текстовый результат выполнения доступен в AgentRunResponse.Text или AgentRunResponse.ToString(). Все сообщения, созданные в рамках ответа, возвращаются в списке AgentRunResponse.Messages . Это может включать сообщения вызова средства, результаты функции, обновления причин и окончательные результаты.

AgentRunResponse agentResponse = await agent.RunAsync(userInput, thread);

7. Вызов потоковой передачи агента

Основные различия находятся в именах методов от InvokeRun, возвращаемых типов и параметров AgentRunOptions.

Семантическое ядро

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

Платформа агента

Agent Framework имеет аналогичный шаблон API потоковой передачи, при этом ключевое различие заключается в том, что он возвращает AgentRunResponseUpdate объекты, содержащие дополнительные сведения, связанные с агентом на обновление.

Возвращаются все обновления, созданные любой службой, базовой службой AIAgent. Текстовый результат агента доступен путем объединения значений AgentRunResponse.Text .

await foreach (AgentRunResponseUpdate update in agent.RunStreamingAsync(userInput, thread))
{
    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) };

Решение. Упрощенные параметры в Agent Framework.

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

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>(),
        });

Платформа агента

Agent Framework предоставляет AIAgent тип в качестве базового класса абстракции.

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

11. Консолидация типов агента

Семантическое ядро

Семантический ядро предоставляет определенные классы агентов для различных служб, например:

• ChatCompletionAgent для использования с службами вывода на основе чата.
• OpenAIAssistantAgent для использования со службой Помощников OpenAI.
• AzureAIAgent для использования со службой Агентов Azure AI Foundry.

Платформа агента

Agent Framework поддерживает все упомянутые службы с помощью одного типа ChatClientAgentагента.

ChatClientAgent можно использовать для создания агентов с помощью любой базовой службы, предоставляющей пакет SDK, реализующий IChatClient интерфейс.

Основные отличия

Ниже приведена сводка ключевых различий между платформой агента семантического ядра и Платформой Microsoft Agent Framework, помогая перенести код.

1. Пакет и импорт обновлений

Семантическое ядро

Пакеты семантического ядра устанавливаются как semantic-kernel и импортируются как semantic_kernel. Пакет также содержит ряд extras компонентов, которые можно установить для установки различных зависимостей для разных поставщиков ИИ и других функций.

from semantic_kernel import Kernel
from semantic_kernel.agents import ChatCompletionAgent

Платформа агента

Пакет Agent Framework устанавливается как agent-framework и импортируется как agent_framework. Платформа агента создается по-разному, она содержит основной пакет agent-framework-core , содержащий основные функциональные возможности, а затем существует несколько пакетов, которые полагаются на этот основной пакет, например agent-framework-azure-ai, agent-framework-mem0и agent-framework-copilotstudioт. д. При запуске pip install agent-framework он установит основной пакет и все пакеты, чтобы быстро приступить к работе со всеми функциями. Когда вы готовы сократить количество пакетов, так как вы знаете, что вам нужно, вы можете установить только необходимые пакеты, поэтому, например, если вы планируете использовать Azure AI Foundry и Mem0, вы можете установить только эти два пакета: pip install agent-framework-azure-ai agent-framework-mem0agent-framework-core это зависимость от этих двух, поэтому автоматически будет установлена.

Несмотря на то, что пакеты разделены, импорты все из agent_frameworkмодулей или это модули. Таким образом, например, чтобы импортировать клиент для Azure AI Foundry, выполните следующие действия:

from agent_framework.azure import AzureAIAgentClient

Многие из наиболее часто используемых типов импортируются напрямую из agent_framework:

from agent_framework import ChatMessage, ChatAgent

2. Консолидация типов агента

Семантическое ядро

Семантический ядро предоставляет определенные классы агентов для различных служб, например ChatCompletionAgent, AzureAIAgent, OpenAIAssistantAgent и т. д. См. типы агентов в семантическом ядре.

Платформа агента

В Agent Framework большинство агентов создаются ChatAgent с помощью ChatClient всех служб на основе, таких как Azure AI Foundry, OpenAI ChatCompletion и OpenAI Responses. Существует два дополнительных агента: CopilotStudioAgent для использования с Copilot Studio и A2AAgent для использования с A2A.

Все встроенные агенты основаны на BaseAgent (from agent_framework import BaseAgent). Все агенты согласованы с интерфейсом AgentProtocol (from agent_framework import AgentProtocol).

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.",
)

Платформа агента

Создание агента в Agent Framework можно сделать двумя способами:

from agent_framework.azure import AzureAIAgentClient
from agent_framework import ChatMessage, ChatAgent

agent = ChatAgent(chat_client=AzureAIAgentClient(credential=AzureCliCredential()), instructions="You are a helpful assistant")

Или с помощью удобных методов, предоставляемых клиентами чата:

from agent_framework.azure import AzureOpenAIChatClient
from azure.identity import AzureCliCredential
agent = AzureOpenAIChatClient(credential=AzureCliCredential()).create_agent(instructions="You are a helpful assistant")

Прямой метод предоставляет все возможные параметры, которые можно задать для агента. Хотя удобный метод имеет подмножество, вы по-прежнему можете передать один и тот же набор параметров, так как он вызывает прямой метод внутренне.

4. Создание потока агента

Семантическое ядро

Вызывающий объект должен знать тип потока и создать его вручную.

from semantic_kernel.agents import ChatHistoryAgentThread

thread = ChatHistoryAgentThread()

Платформа агента

Агенту может быть предложено создать новый поток.

agent = ...
thread = agent.get_new_thread()

Затем поток создается одним из трех способов:

1. Если агент имеет thread_id набор (или conversation_id что-то подобное), он создаст поток в базовой службе с таким идентификатором. После наличия service_thread_idпотока вы больше не можете использовать его для хранения сообщений в памяти. Это относится только к агентам, имеющим концепцию потока на стороне службы. Например, агенты Azure AI Foundry и помощники OpenAI.
2. Если агент имеет chat_message_store_factory набор, он будет использовать ее для создания хранилища сообщений и использования этого для создания потока в памяти. Затем его нельзя использовать с агентом с заданным параметром storeTrue.
3. Если ни один из предыдущих параметров не задан, он считается uninitialized и в зависимости от того, как он используется, он станет потоком в памяти или потоком службы.

Платформа агента

Agent Framework не имеет API удаления потоков в типе AgentThread , так как не все поставщики поддерживают размещенные потоки или удаление потоков, и это становится более распространенным, так как все поставщики переместятся на архитектуры на основе ответов.

Если требуется удаление потоков и поставщик разрешает это, вызывающий объект должен отслеживать созданные потоки и удалять их позже с помощью пакета SDK поставщика.

Поставщик помощников OpenAI:

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

5. Регистрация инструментов

Семантическое ядро

Чтобы предоставить функцию в качестве инструмента, необходимо:

1. Украшайте функцию декоратором @kernel_function .
2. Plugin Создайте класс или используйте фабрику подключаемых модулей ядра для оболочки функции.
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.create_agent(tools=get_weather)

Затем имя функции станет именем средства, а документация станет описанием инструмента, вы также можете добавить описание в параметры:

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 ai_function

@ai_function(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.create_agent(tools=[plugin.get_weather, plugin.get_weather_details])

... # use the agent

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

Этот механизм также полезен для инструментов, требующих дополнительных входных данных, которые не могут быть предоставлены LLM, например подключения, секреты и т. д.

Совместимость. Использование KernelFunction в качестве средств agent Framework

Если у вас есть код семантического ядра с KernelFunction экземплярами (из запросов или методов), их можно преобразовать в средства Agent Framework с помощью .as_agent_framework_tool метода.

Использование 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 OpenAIResponsesClient

# Create a kernel with services and plugins
kernel = Kernel()
# will get the api_key and model_id 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 = OpenAIResponsesClient(model_id="gpt-4o").create_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 OpenAIResponsesClient

# 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 = OpenAIResponsesClient(model_id="gpt-4o").create_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 объект, который можно преобразовать в средство Agent Framework.

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 OpenAIResponsesClient

# 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 = OpenAIResponsesClient(model_id="gpt-4o").create_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.

Этот уровень совместимости позволяет постепенно перенести код из семантического ядра в Agent Framework, повторно используя существующие KernelFunction реализации, используя упрощенные шаблоны создания и выполнения агента в Платформе агента.

6. Вызов без потоковой передачи агента

Ключевые различия можно увидеть в именах методов от invokerun, возвращаемых типов (например, AgentRunResponse) и параметров.

Семантическое ядро

Вызов без потоковой передачи использует шаблон асинхронного итератора для возврата нескольких сообщений агента.

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}")

Платформа агента

Выполнение без потоковой передачи возвращает один с AgentRunResponse ответом агента, который может содержать несколько сообщений. Текстовый результат выполнения доступен в response.text или str(response). Все сообщения, созданные в рамках ответа, возвращаются в списке response.messages . Это может включать сообщения вызова средства, результаты функции, обновления причин и окончательные результаты.

agent = ...

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

7. Вызов потоковой передачи агента

Ключевые различия в именах методов от invokerun_stream, возвращаемых типов (AgentRunResponseUpdate) и параметров.

Семантическое ядро

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)

Платформа агента

Аналогичный шаблон API потоковой передачи с ключевым различием заключается в том, что он возвращает AgentRunResponseUpdate объекты, включая дополнительные сведения об агенте для каждого обновления.

Возвращается все содержимое, созданное любой службой, базовой агентом. Окончательный результат агента доступен путем объединения update значений в один ответ.

from agent_framework import AgentRunResponse
agent = ...
updates = []
async for update in agent.run_stream(user_input, thread):
    updates.append(update)
    print(update.text)

full_response = AgentRunResponse.from_agent_run_response_updates(updates)
print("Full agent response:", full_response.text)

Это можно сделать даже напрямую:

from agent_framework import AgentRunResponse
agent = ...
full_response = AgentRunResponse.from_agent_response_generator(agent.run_stream(user_input, thread))
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)

Решение: упрощенные параметры в Agent Framework

Agent Framework позволяет передавать все параметры непосредственно в соответствующие методы, чтобы не нужно импортировать дополнительные объекты или создавать объекты параметров, если вы не хотите. Внутри него используется ChatOptions объект, для ChatClients которого ChatAgentsможно также создать и передать его, если вы хотите. Это также создается в объекте ChatAgent для хранения параметров и может быть переопределено для каждого вызова.

agent = ...

response = await agent.run(user_input, thread, max_tokens=1000, frequency_penalty=0.5)