Průvodce migrací sémantického jádra do architektury agentů

Výhody rozhraní Microsoft Agent Framework

• Zjednodušené rozhraní API: Menší složitost a často používaný kód
• Lepší výkon: Optimalizované vytváření objektů a využití paměti.
• Jednotné rozhraní: Konzistentní vzory napříč různými poskytovateli AI
• Vylepšené prostředí pro vývojáře: Intuitivnější a zjistitelná rozhraní API

Následující části shrnují klíčové rozdíly mezi sémantickou architekturou agenta jádra a rozhraním Microsoft Agent Framework, které vám pomůžou s migrací kódu.

1. Aktualizace oboru názvů

Sémantické jádro

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

Agentní rámec

Obory názvů rozhraní Agent Framework jsou pod Microsoft.Agents.AI. Agent Framework používá základní zprávy AI a typy obsahu pro Microsoft.Extensions.AI komunikaci mezi komponentami.

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

2. Zjednodušení vytváření agentů

Sémantické jádro

Každý agent v sémantickém jádru závisí na instanci a má prázdnou KernelKernel , pokud není k dispozici.

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

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

Microsoft Foundry vyžaduje vytvoření prostředku agenta v cloudu před vytvořením místní třídy agenta, která ho používá.

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

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

AzureAIAgent agent = new(definition, azureAgentClient);

Výstraha

DefaultAzureCredential je vhodný pro vývoj, ale vyžaduje pečlivé zvážení v produkčním prostředí. V produkčním prostředí zvažte použití konkrétních přihlašovacích údajů (např ManagedIdentityCredential. ) k zabránění problémům s latencí, neúmyslnému testování přihlašovacích údajů a potenciálním bezpečnostním rizikům z náhradních mechanismů.

Agentní rámec

Vytváření agentů v rozhraní Agent Framework je jednodušší s rozšířeními poskytovanými všemi hlavními poskytovateli.

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

Kromě toho můžete pro hostované poskytovatele agentů použít také metodu AsAIAgent k načtení agenta z existujícího záznamu hostovaného agenta.

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

3. Vlákno agenta nebo vytvoření relace

Sémantické jádro

Volající musí znát typ vlákna a vytvořit ho ručně.

// 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);

Agentní rámec

Agent zodpovídá za vytvoření relace.

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

4. Vlákno hostovaného agenta nebo vyčištění relace

Tento případ platí výhradně pro několik poskytovatelů AI, kteří stále poskytují hostovaná vlákna.

Sémantické jádro

Vlákna mají metodu self odstranění.

Zprostředkovatel pomocníků OpenAI:

await thread.DeleteAsync();

Agentní rámec

Poznámka:

Odpovědi OpenAI zavedly nový model konverzace, který zjednodušuje způsob zpracování konverzací. Tato změna zjednodušuje správu historie hostovaných chatů v porovnání s aktuálně zastaralým modelem pomocníků OpenAI. Další informace najdete v průvodci migrací pomocníků OpenAI.

Rozhraní Agent Framework nemá v typu historii chatu ani rozhraní API pro AgentSession odstraňování relací, protože ne všichni poskytovatelé nepodporují historii hostovaných chatů ani odstranění historie chatu.

Pokud vyžadujete odstranění historie chatu a poskytovatel to umožňuje, měl by volající sledovat vytvořené relace a později odstranit související chat hsitory prostřednictvím sady SDK poskytovatele.

Zprostředkovatel pomocníků OpenAI:

await assistantClient.DeleteThreadAsync(session.ConversationId);

5. Registrace nástroje

Sémantické jádro

Pokud chcete funkci zveřejnit jako nástroj, musíte:

1. Ozdobte funkci atributem [KernelFunction] .
2. Plugin Mít třídu nebo použít KernelPluginFactory k zabalení funkce.
3. Kernel Musíte přidat modul plug-in.
4. Kernel Předejte agenta.

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

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

Agentní rámec

V rozhraní Agent Framework můžete v jednom volání zaregistrovat nástroje přímo v procesu vytváření agenta.

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

6. Volání agenta bez streamování

Hlavní rozdíly lze vidět v názvech metod od Invoke do Run, návratové typy a parametry AgentRunOptions.

Sémantické jádro

Non-Streaming používá vzor IAsyncEnumerable<AgentResponseItem<ChatMessageContent>> streamování pro vrácení více zpráv agenta.

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

Agentní rámec

Non-Streaming vrátí jeden AgentResponse s odpovědí agenta, který může obsahovat více zpráv. Textový výsledek spuštění je k dispozici v AgentResponse.Text nebo AgentResponse.ToString(). V seznamu se vrátí AgentResponse.Messages všechny zprávy vytvořené jako součást odpovědi. To může zahrnovat zprávy volání nástroje, výsledky funkcí, aktualizace důvodů a konečné výsledky.

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

7. Vyvolání streamování agenta

Hlavní rozdíly jsou v názvech metod od Invoke do Run, návratové typy a parametry AgentRunOptions.

Sémantické jádro

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

Agentní rámec

Agent Framework má podobný vzor rozhraní API streamování, přičemž klíčovým rozdílem je, že vrací AgentResponseUpdate objekty, které obsahují více informací souvisejících s agenty na aktualizaci.

Vrátí se všechny aktualizace vytvořené jakoukoli službou, která je podkladem agenta AIAgent. Textový výsledek agenta je k dispozici zřetězením AgentResponse.Text hodnot.

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

8. Podpisy funkcí nástrojů

Problém: Sémantické metody modulu plug-in jádra potřebují [KernelFunction] atributy.

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

Řešení: Rozhraní agenta může používat metody přímo bez atributů.

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

9. Konfigurace možností

Problém: Nastavení složitých možností v sémantickém jádru

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

Řešení: Zjednodušené možnosti v architektuře agenta

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

Důležité

Tento příklad ukazuje předávání možností specifických pro implementaci do .ChatClientAgent Ne všechna AIAgents podpora ChatClientAgentRunOptions. ChatClientAgent je poskytován pro vytváření agentů založených na podkladových službách odvození, a proto podporuje možnosti odvození, jako je MaxOutputTokens.

10. Injektáž závislostí

Sémantické jádro

Aby Kernel bylo možné vytvořit agenta, je vyžadována registrace v kontejneru služby, protože každá abstrakce agenta musí být inicializována vlastností Kernel .

Sémantické jádro používá Agent typ jako základní abstrakci třídy pro agenty.

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

Agentní rámec

Agent Framework poskytuje AIAgent typ jako základní abstrakci třídy.

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

11. Konsolidace typů agentů

Sémantické jádro

Sémantické jádro poskytuje specifické třídy agentů pro různé služby, například:

• ChatCompletionAgent pro použití se službami odvozování na základě chatu.
• OpenAIAssistantAgent pro použití se službou OpenAI Assistants.
• AzureAIAgent pro použití se službou Foundry Agent Service.

Agentní rámec

Agent Framework podporuje všechny uvedené služby prostřednictvím jednoho typu agenta . ChatClientAgent

ChatClientAgent lze použít k sestavení agentů pomocí jakékoli podkladové služby, která poskytuje sadu SDK, která implementuje IChatClient rozhraní.

Hlavní rozdíly

Tady je souhrn klíčových rozdílů mezi sémantickou architekturou agenta jádra a rozhraním Microsoft Agent Framework, které vám pomůžou s migrací kódu.

1. Balení a import aktualizací

Sémantické jádro

Sémantické balíčky jádra jsou nainstalovány jako semantic-kernel a importovány jako semantic_kernel. Balíček má také řadu extras , které můžete nainstalovat, abyste nainstalovali různé závislosti pro různé poskytovatele AI a další funkce.

from semantic_kernel import Kernel
from semantic_kernel.agents import ChatCompletionAgent

Agentní rámec

Balíček Agent Framework je nainstalován jako agent-framework a importován jako agent_framework. Agent Framework je sestaven jinak, má základní balíčekagent-framework-core, který obsahuje základní funkce, a pak existuje více balíčků, které spoléhají na tento základní balíček, například agent-framework-openai, , agent-framework-foundryagent-framework-mem0, agent-framework-copilotstudioatd. Když ho spustítepip install agent-framework, nainstaluje se základní balíček a balíčky poskytovatele, které se dodávají do metabalíku, abyste mohli rychle začít s běžnými funkcemi. Až budete připraveni snížit počet balíčků, protože víte, co potřebujete, můžete nainstalovat pouze balíčky, které potřebujete, takže pokud plánujete používat pouze Foundry a Mem0, můžete nainstalovat pouze tyto dva balíčky: pip install --pre agent-framework-foundry agent-framework-mem0, agent-framework-core je závislost na těchto dvou, takže se automaticky nainstaluje.

I když jsou balíčky rozdělené, importy jsou všechny z agent_framework, nebo z modulů. Například k importu klienta pro Foundry byste udělali:

from agent_framework.foundry import FoundryChatClient

Mnohé z nejčastěji používaných typů se importují přímo z agent_framework:

from agent_framework import Message, Agent

2. Konsolidace typů agentů

Sémantické jádro

Sémantické jádro poskytuje specifické třídy agentů pro různé služby, například ChatCompletionAgent, AzureAIAgent, OpenAIAssistantAgent atd. Viz Typy agentů v sémantickém jádru.

Agentní rámec

V rozhraní Agent Framework se většina agentů vytváří pomocí Agent toho, které lze použít se všemi ChatClient založenými službami, jako jsou Foundry, OpenAI ChatCompletion a OpenAI Odpovědi. Existují dva další agenti: CopilotStudioAgent pro použití se sadou Copilot Studio a A2AAgent pro použití s A2A.

Všechny předdefinované agenty jsou založené na agentu BaseAgent (from agent_framework import BaseAgent). A všichni agenti jsou konzistentní s rozhraním SupportsAgentRun (from agent_framework import SupportsAgentRun).

3. Zjednodušení vytváření agentů

Sémantické jádro

Každý agent v sémantickém jádru Kernel závisí na instanci a pokud není zadaný, bude mít prázdný 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.",
)

Agentní rámec

Vytvoření agenta v rozhraní Agent Framework lze provést dvěma způsoby, a to přímo:

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

Nebo s metodami pohodlí poskytovanými chatovacími klienty:

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

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

Přímá metoda zveřejňuje všechny možné parametry, které můžete pro svého agenta nastavit. I když má metoda pohodlí podmnožinu, můžete stále předat stejnou sadu parametrů, protože volá přímou metodu interně.

4. Vytvoření vlákna agenta

Sémantické jádro

Volající musí znát typ vlákna a vytvořit ho ručně.

from semantic_kernel.agents import ChatHistoryAgentThread

thread = ChatHistoryAgentThread()

Agentní rámec

Agenta můžete požádat o vytvoření nového vlákna za vás.

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

Vlákno se pak vytvoří jedním ze tří způsobů:

1. Pokud má agent nastavenou thread_id (nebo conversation_id něco podobného), vytvoří vlákno v podkladové službě s tímto ID. Jakmile vlákno obsahuje service_thread_id, už ho nemůžete použít k ukládání zpráv do paměti. To platí jenom pro agenty, kteří mají koncept vlákna na straně služby. jako jsou agenti Foundry a asistenti OpenAI.
2. Pokud má chat_message_store_factory agent sadu, použije tuto továrnu k vytvoření úložiště zpráv a použije ho k vytvoření vlákna v paměti. Poté již nelze použít s agentem s parametrem nastaveným store na True.
3. Pokud není nastavená žádná z předchozích nastavení, považuje uninitialized se za ni a v závislosti na způsobu jeho použití se buď stane vlákno v paměti, nebo vlákno služby.

Agentní rámec

Poznámka:

Odpovědi OpenAI zavedly nový model konverzace, který zjednodušuje způsob zpracování konverzací. To zjednodušuje správu hostovaných vláken v porovnání s aktuálně zastaralým modelem OpenAI Assistants. Další informace najdete v průvodci migrací pomocníků OpenAI.

Rozhraní Agent Framework nemá rozhraní API pro odstranění vlákna v AgentThread typu, protože ne všichni poskytovatelé podporují hostovaná vlákna nebo odstraňování vláken a stává se to častějším, protože více poskytovatelů přechází na architektury založené na odpovědích.

Pokud požadujete odstranění vlákna a poskytovatel to umožňuje, volající by měl sledovat vytvořené vlákna a odstranit je později v případě potřeby prostřednictvím sady SDK poskytovatele.

Zprostředkovatel pomocníků OpenAI:

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

5. Registrace nástroje

Sémantické jádro

Pokud chcete funkci zveřejnit jako nástroj, musíte:

1. Ozdobte funkci dekorátorem @kernel_function .
2. Plugin Máte třídu nebo použijte továrnu modulu plug-in jádra k zabalení funkce.
3. Kernel Musíte přidat modul plug-in.
4. Kernel Předejte agenta.

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()],
)

Agentní rámec

V jednom volání můžete zaregistrovat nástroje přímo v procesu vytváření agenta. Agent Framework nemá koncept modulu plug-in pro zabalení více funkcí, ale v případě potřeby to můžete přesto udělat.

Nejjednodušší způsob, jak vytvořit nástroj, je jen vytvořit funkci Pythonu:

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)

Poznámka:

Parametr tools je k dispozici při vytváření agenta run i metodě (s nebo bez stream=True), stejně jako get_response metody a get_streaming_response metody, umožňuje poskytnout nástroje jako seznam nebo jednu funkci.

Název funkce se pak stane názvem nástroje a řetězec docstring se stane popisem nástroje, můžete také přidat popis parametrů:

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

Nakonec můžete pomocí dekorátoru dále přizpůsobit název a popis nástroje:

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

Funguje to také při vytváření třídy s více nástroji jako metodami.

Při vytváření agenta teď můžete do agenta poskytnout nástroj funkce tak, že ho předáte parametru 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)

Poznámka:

Funkce v rámci třídy mohou být také zdobeny tak @tool , aby přizpůsobily název a popis nástrojů.

Tento mechanismus je také užitečný pro nástroje, které potřebují další vstup, které LLM nemůže zadat, jako jsou připojení, tajné kódy atd.

Kompatibilita: Použití jádraFunction jako nástrojů agenta Framework

Pokud máte existující kód sémantického jádra s instancemi KernelFunction (buď z výzev, nebo z metod), můžete je pomocí této metody převést na nástroje .as_agent_framework_tool Agent Framework.

Důležité

Tato funkce vyžaduje semantic-kernel verzi 1.38 nebo vyšší.

Použití funkce KernelFunction ze šablony výzvy

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)

Použití kernelFunction z metody

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)

Použití vectorstore s create_search_function

Sémantické integrace VectorStore jádra můžete použít také s architekturou Agent Framework. Metoda create_search_function z kolekce vektorového úložiště vrací metodu KernelFunction , kterou lze převést na nástroj 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 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)

Tento model funguje s jakýmkoli konektorem Semantic Kernel VectorStore (Azure AI Search, Qdrant, Pinecone atd.), který umožňuje využít stávající infrastrukturu vektorového vyhledávání s agenty Agent Framework.

Tato vrstva kompatibility umožňuje postupně migrovat kód ze sémantického jádra do rozhraní Agent Framework a opakovaně používat stávající KernelFunction implementace a využívat zjednodušené vytváření a spouštění agentů rozhraní Agent Framework.

6. Volání agenta bez streamování

Hlavní rozdíly lze vidět v názvech metod od invoke do run, návratové typy (například AgentResponse) a parametry.

Sémantické jádro

Volání bez streamování používá vzor asynchronního iterátoru pro vrácení více zpráv agenta.

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

A k získání konečné odpovědi došlo k usnadnění:

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

Agentní rámec

Spuštění bez streamování vrátí jednu AgentResponse odpověď agenta, která může obsahovat více zpráv. Textový výsledek spuštění je k dispozici v response.text nebo str(response). V seznamu se vrátí response.messages všechny zprávy vytvořené jako součást odpovědi. To může zahrnovat zprávy volání nástroje, výsledky funkcí, odůvodnění aktualizací a konečné výsledky.

agent = ...

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

7. Vyvolání streamování agenta

Hlavní rozdíly v názvech metod od invoke do run(..., stream=True), návratové typy (AgentResponseUpdate) a parametry.

Sémantické jádro

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)

Agentní rámec

Podobný vzor rozhraní API streamování s klíčovým rozdílem v tom, že vrací AgentResponseUpdate objekty, včetně dalších informací souvisejících s agenty na aktualizaci.

Vrátí se veškerý obsah vytvořený jakoukoli službou, která je podkladem agenta. Konečný výsledek agenta je k dispozici kombinací update hodnot do jedné odpovědi.

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

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

Můžete to dokonce udělat přímo:

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

8. Konfigurace možností

Problém: Nastavení složitých možností v sémantickém jádru

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)

Řešení: Zjednodušené možnosti založené na diktování v architektuře agentů

Agent Framework používá systém možností založený na TypedDict pro ChatClients a Agents. Možnosti se předávají prostřednictvím jednoho options parametru jako typového slovníku, přičemž třídy TypedDict specifické pro zprostředkovatele (například OpenAIChatOptions) pro úplné automatické dokončování integrovaného vývojového prostředí a kontrolu typů.

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

Poznámka:

Parametry tools zůstávají jako argumenty přímého klíčového slova pro vytváření a instructions metody agenta a nejsou předány prostřednictvím slovníkurun().options Podrobné vzory migrace najdete v průvodci upgradem možností typů .

Další kroky

Příručka pro rychlý start