Průvodce migrací Agent Framework verze Release Candidate

Běžné rozhraní API pro vyvolání agenta

Ve verzi 1.43.0 vydáváme nové společné rozhraní API pro vyvolání agenta, které umožní vyvolání všech typů agentů prostřednictvím společného rozhraní API.

Abychom umožnili toto nové rozhraní API, představujeme koncept AgentThread, který představuje vlákno konverzace a abstrahuje různé požadavky na správu vláken různých typů agentů. U některých typů agentů také v budoucnu umožní použití různých implementací vláken se stejným agentem.

Běžné Invoke metody, které zavádíme, umožňují zadat zprávy, které chcete předat agentovi, a volitelný AgentThread. Pokud je k dispozici AgentThread, konverzace bude pokračovat již probíhající na AgentThread. Pokud není k dispozici žádná AgentThread, vytvoří se nové výchozí vlákno a vrátí se jako součást odpovědi.

Je také možné ručně vytvořit instanci AgentThread, například v případech, kdy můžete mít ID vlákna z podkladové služby agenta a chcete pokračovat v tomto vlákně. Můžete také přizpůsobit možnosti vlákna, například přidružit nástroje.

Tady je jednoduchý příklad použití libovolného agenta s kódem, který je nezávislý na agentech.

private async Task UseAgentAsync(Agent agent, AgentThread? agentThread = null)
{
    // Invoke the agent, and continue the existing thread if provided.
    var responses = agent.InvokeAsync(new ChatMessageContent(AuthorRole.User, "Hi"), agentThread);

    // Output results.
    await foreach (AgentResponseItem<ChatMessageContent> response in responses)
    {
        Console.WriteLine(response);
        agentThread = response.Thread;
    }

    // Delete the thread if required.
    if (agentThread is not null)
    {
        await agentThread.DeleteAsync();
    }
}

Tyto změny byly použity v:

• PR č. 11116

Možnosti vláken agenta Azure AI

AzureAIAgent aktuálně podporuje pouze vlákna typu AzureAIAgentThread.

Kromě automatického vytvoření vlákna pro vás při vyvolání agenta si můžete také ručně vytvořit instanci AzureAIAgentThread.

AzureAIAgentThread podporuje vytváření s přizpůsobenými nástroji a metadaty, a také zasílání zpráv k zahájení konverzace.

AgentThread thread = new AzureAIAgentThread(
    agentsClient,
    messages: seedMessages,
    toolResources: tools,
    metadata: metadata);

Můžete také vytvořit instanci AzureAIAgentThread, která pokračuje v existující konverzaci.

AgentThread thread = new AzureAIAgentThread(
    agentsClient,
    id: "my-existing-thread-id");

Možnosti vláken bedrockového agenta

BedrockAgent aktuálně podporuje pouze vlákna typu BedrockAgentThread.

Kromě automatického vytvoření vlákna pro vás při vyvolání agenta si můžete také ručně vytvořit instanci BedrockAgentThread.

AgentThread thread = new BedrockAgentThread(amazonBedrockAgentRuntimeClient);

Můžete také vytvořit instanci BedrockAgentThread, která pokračuje v existující konverzaci.

AgentThread thread = new BedrockAgentThread(
    amazonBedrockAgentRuntimeClient,
    sessionId: "my-existing-session-id");

Možnosti vlákna agenta pro dokončování chatu

ChatCompletionAgent aktuálně podporuje pouze vlákna typu ChatHistoryAgentThread. ChatHistoryAgentThread používá objekt ChatHistory v paměti k uložení zpráv ve vlákně.

Kromě automatického vytvoření vlákna pro vás při vyvolání agenta si můžete také ručně vytvořit instanci ChatHistoryAgentThread.

AgentThread thread = new ChatHistoryAgentThread();

Můžete také vytvořit instanci ChatHistoryAgentThread, která pokračuje v existující konverzaci předáním objektu ChatHistory s existujícími zprávami.

ChatHistory chatHistory = new([new ChatMessageContent(AuthorRole.User, "Hi")]);

AgentThread thread = new ChatHistoryAgentThread(chatHistory: chatHistory);

Možnosti vlákna asistenta OpenAI

OpenAIAssistantAgent aktuálně podporuje pouze vlákna typu OpenAIAssistantAgentThread.

Kromě automatického vytvoření vlákna pro vás při vyvolání agenta si můžete také ručně vytvořit instanci OpenAIAssistantAgentThread.

OpenAIAssistantAgentThread podporuje vytváření s přizpůsobenými nástroji a metadaty, a také zasílání zpráv k zahájení konverzace.

AgentThread thread = new OpenAIAssistantAgentThread(
    assistantClient,
    messages: seedMessages,
    codeInterpreterFileIds: fileIds,
    vectorStoreId: "my-vector-store",
    metadata: metadata);

Můžete také vytvořit instanci OpenAIAssistantAgentThread, která pokračuje v existující konverzaci.

AgentThread thread = new OpenAIAssistantAgentThread(
    assistantClient,
    id: "my-existing-thread-id");

Průvodce migrací openAIAssistantAgent C#

Nedávno jsme použili významný posun v rámci OpenAIAssistantAgent v sémantickém jádru agentního frameworku.

Tyto změny byly použity v:

• PR č. 10583
• PR č. 10616
• PR č. 10633

Tyto změny jsou určeny k tomu, aby:

• Zarovnejte se s návodem pro užití našeho AzureAIAgent.
• Opravte chyby související se vzorem statické inicializace.
• Vyhněte se omezení funkcí na základě naší abstrakce podkladové sady SDK.

Tento průvodce obsahuje podrobné pokyny pro migraci kódu jazyka C# ze staré implementace na novou. Mezi změny patří aktualizace pro vytváření asistentů, správa životního cyklu asistenta, zpracování vláken, souborů a úložišť vektorů.

1. Vytvoření instance klienta

Dříve bylo nutné OpenAIClientProvider k vytvoření libovolného OpenAIAssistantAgent. Tato závislost byla zjednodušená.

nový způsob

OpenAIClient client = OpenAIAssistantAgent.CreateAzureOpenAIClient(new AzureCliCredential(), new Uri(endpointUrl));
AssistantClient assistantClient = client.GetAssistantClient();

Starý způsob (zastaralý)

var clientProvider = new OpenAIClientProvider(...);

2. Životní cyklus pomocníka

Vytvoření pomocníka

Nyní můžete přímo vytvořit instanci OpenAIAssistantAgent ze stávající nebo nové definice asistenta z AssistantClient.

nový způsob

Assistant definition = await assistantClient.GetAssistantAsync(assistantId);
OpenAIAssistantAgent agent = new(definition, client);

Moduly plug-in je možné přímo zahrnout během inicializace:

KernelPlugin plugin = KernelPluginFactory.CreateFromType<YourPlugin>();
Assistant definition = await assistantClient.GetAssistantAsync(assistantId);
OpenAIAssistantAgent agent = new(definition, client, [plugin]);

Vytvoření nové definice asistenta pomocí metody rozšíření:

Assistant assistant = await assistantClient.CreateAssistantAsync(
    model,
    name,
    instructions: instructions,
    enableCodeInterpreter: true);

Starý způsob (zastaralý)

Dříve byly definice asistentů spravovány nepřímo.

3. Vyvolání agenta

Můžete zadat přímo RunCreationOptions a povolit úplný přístup k základním funkcím sady SDK.

nový způsob

RunCreationOptions options = new(); // configure as needed
var result = await agent.InvokeAsync(options);

Starý způsob (zastaralý)

var options = new OpenAIAssistantInvocationOptions();

4. Odstranění asistenta

Odstranění asistenta můžete spravovat přímo pomocí AssistantClient.

await assistantClient.DeleteAssistantAsync(agent.Id);

5. Životní cyklus vlákna

Vytvoření vlákna

Vlákna jsou nyní spravována pomocí AssistantAgentThread.

nový způsob

var thread = new AssistantAgentThread(assistantClient);
// Calling CreateAsync is an optional step.
// A thread will be created automatically on first use if CreateAsync was not called.
// Note that CreateAsync is not on the AgentThread base implementation since not all
// agent services support explicit thread creation.
await thread.CreateAsync();

Starý způsob (zastaralý)

Dříve byla správa vláken nepřímá nebo vázaná na agenta.

Odstranění vlákna

var thread = new AssistantAgentThread(assistantClient, "existing-thread-id");
await thread.DeleteAsync();

6. Životní cyklus souborů

Vytváření a odstraňování souborů nyní využívá OpenAIFileClient.

Nahrání souboru

string fileId = await client.UploadAssistantFileAsync(stream, "<filename>");

Mazání souboru

await client.DeleteFileAsync(fileId);

7. Životní cyklus úložiště vektorů

Vektorová úložiště se spravují přímo prostřednictvím VectorStoreClient s pohodlnými rozšiřujícími metodami.

Vytvoření Úložiště Vektorů

string vectorStoreId = await client.CreateVectorStoreAsync([fileId1, fileId2], waitUntilCompleted: true);

Odstranění úložiště vektorů

await client.DeleteVectorStoreAsync(vectorStoreId);

Zpětná kompatibilita

Zastaralé vzory jsou označené [Obsolete]. Chcete-li potlačit zastaralá upozornění (CS0618), aktualizujte soubor projektu následujícím způsobem:

<PropertyGroup>
  <NoWarn>$(NoWarn);CS0618</NoWarn>
</PropertyGroup>

Tento průvodce migrací vám pomůže hladce přejít na novou implementaci, zjednodušit inicializaci klientů, správu prostředků a integraci se sadou sémantické jádro .NET SDK.

Tyto změny byly použity v:

• PR č. 11116

Předchozí změny byly použity v:

• PR č. 10666
• PR č. 10667
• PR č. 10701
• PR č. 10707

Tento průvodce obsahuje podrobné pokyny pro migraci kódu Pythonu ze staré implementace na novou implementaci.

Import agentů

Všechny importní cesty agentů byly sjednoceny pod semantic_kernel.agents.

Aktualizovaný styl importu

from semantic_kernel.agents import (
    AutoGenConversableAgent,
    AzureAIAgent,
    AzureAssistantAgent,
    BedrockAgent,
    ChatCompletionAgent,
    OpenAIAssistantAgent,
)

Předchozí styl importu (zastaralý):

from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.agents.autogen import AutoGenConversableAgent
from semantic_kernel.agents.azure_ai import AzureAIAgent
from semantic_kernel.agents.bedrock import BedrockAgent
from semantic_kernel.agents.open_ai import AzureAssistantAgent, OpenAIAssistantAgent

Běžné rozhraní API pro vyvolání agenta

Od sémantického jádra Python 1.26.0 a novější jsme zavedli novou společnou abstrakci pro správu vláken pro všechny agenty. Pro každého agenta nyní zveřejňujeme třídu vlákna, která implementuje základní třídu AgentThread, což umožňuje správu kontextu prostřednictvím metod, jako jsou create() a delete().

Odpovědi agenta get_response(...), invoke(...), invoke_stream(...) nyní vrací AgentResponseItem[ChatMessageContent], který má dva atributy:

message: TMessage  # Usually ChatMessageContent
thread: AgentThread  # Contains the concrete type for the given agent

Přidání zpráv do vlákna

Zprávy by měly být přidány do vlákna jako součást agentových metod messages, get_response(...), nebo invoke(...) prostřednictvím argumentu invoke_stream(...).

Vlákno agenta Azure AI

AzureAIAgentThread lze vytvořit následujícím způsobem:

from semantic_kernel.agents import AzureAIAgentThread

thread = AzureAIAgentThread(
    client: AIProjectClient,  # required
    messages: list[ThreadMessageOptions] | None = None,  # optional
    metadata: dict[str, str] | None = None,  # optional
    thread_id: str | None = None,  # optional
    tool_resources: "ToolResources | None" = None,  # optional
)

Poskytnutí thread_id (textového řetězce) umožňuje pokračovat v existující konverzaci. Pokud tento parametr vynecháte, vytvoří se nové vlákno a vrátí se jako součást odpovědi agenta.

Kompletní příklad implementace:

import asyncio

from azure.identity.aio import DefaultAzureCredential

from semantic_kernel.agents import AzureAIAgent, AzureAIAgentSettings, AzureAIAgentThread

USER_INPUTS = [
    "Why is the sky blue?",
    "What are we talking about?",
]

async def main() -> None:
    ai_agent_settings = AzureAIAgentSettings.create()

    async with (
        DefaultAzureCredential() as creds,
        AzureAIAgent.create_client(credential=creds) as client,
    ):
        # 1. Create an agent on the Azure AI agent service
        agent_definition = await client.agents.create_agent(
            model=ai_agent_settings.model_deployment_name,
            name="Assistant",
            instructions="Answer the user's questions.",
        )

        # 2. Create a Semantic Kernel agent for the Azure AI agent
        agent = AzureAIAgent(
            client=client,
            definition=agent_definition,
        )

        # 3. Create a thread for the agent
        # If no thread is provided, a new thread will be
        # created and returned with the initial response
        thread: AzureAIAgentThread = None

        try:
            for user_input in USER_INPUTS:
                print(f"# User: {user_input}")
                # 4. Invoke the agent with the specified message for response
                response = await agent.get_response(messages=user_input, thread=thread)
                print(f"# {response.content}: {response}")
                thread = response.thread
        finally:
            # 6. Cleanup: Delete the thread and agent
            await thread.delete() if thread else None
            await client.agents.delete_agent(agent.id)

if __name__ == "__main__":
    asyncio.run(main())

Bedrock Agentní vlákno

BedrockAgent používá BedrockAgentThread ke správě historie konverzací a kontextu. Můžete poskytnout session_id, abyste mohli pokračovat nebo zahájit nový kontext konverzace.

from semantic_kernel.agents import BedrockAgentThread

thread = BedrockAgentThread(
    bedrock_runtime_client: Any,
    session_id: str | None = None,
)

Pokud není k dispozici žádná session_id, vytvoří se automaticky nový kontext.

Kompletní příklad implementace:

import asyncio

from semantic_kernel.agents import BedrockAgent, BedrockAgentThread

async def main():
    bedrock_agent = await BedrockAgent.create_and_prepare_agent(
        "semantic-kernel-bedrock-agent",
        instructions="You are a friendly assistant. You help people find information.",
    )

    # Create a thread for the agent
    # If no thread is provided, a new thread will be
    # created and returned with the initial response
    thread: BedrockAgentThread = None

    try:
        while True:
            user_input = input("User:> ")
            if user_input == "exit":
                print("\n\nExiting chat...")
                break

            # Invoke the agent
            # The chat history is maintained in the session
            response = await bedrock_agent.get_response(
                input_text=user_input,
                thread=thread,
            )
            print(f"Bedrock agent: {response}")
            thread = response.thread
    except KeyboardInterrupt:
        print("\n\nExiting chat...")
        return False
    except EOFError:
        print("\n\nExiting chat...")
        return False
    finally:
        # Delete the agent
        await bedrock_agent.delete_agent()
        await thread.delete() if thread else None


if __name__ == "__main__":
    asyncio.run(main())

Vlákno historie chatu agenta

ChatCompletionAgent používá ke správě historie konverzací ChatHistoryAgentThread. Inicializovat ho můžete takto:

from semantic_kernel.agents import ChatHistoryAgentThread

thread = ChatHistoryAgentThread(
    chat_history: ChatHistory | None = None, 
    thread_id: str | None = None
)

Poskytnutí thread_id umožňuje pokračovat v existujících konverzacích. Vynechání vytvoří nové vlákno. Serializace a obnovování stavu vlákna jsou podporovány pro perzistentní kontexty konverzace.

Kompletní příklad implementace:

import asyncio

from semantic_kernel.agents import ChatCompletionAgent, ChatHistoryAgentThread
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion

# Simulate a conversation with the agent
USER_INPUTS = [
    "Hello, I am John Doe.",
    "What is your name?",
    "What is my name?",
]


async def main():
    # 1. Create the agent by specifying the service
    agent = ChatCompletionAgent(
        service=AzureChatCompletion(),
        name="Assistant",
        instructions="Answer the user's questions.",
    )

    # 2. Create a thread to hold the conversation
    # If no thread is provided, a new thread will be
    # created and returned with the initial response
    thread: ChatHistoryAgentThread = None

    for user_input in USER_INPUTS:
        print(f"# User: {user_input}")
        # 3. Invoke the agent for a response
        response = await agent.get_response(
            messages=user_input,
            thread=thread,
        )
        print(f"# {response.name}: {response}")
        # 4. Store the thread, which allows the agent to
        # maintain conversation history across multiple messages.
        thread = response.thread

    # 5. Cleanup: Clear the thread
    await thread.delete() if thread else None

if __name__ == "__main__":
    asyncio.run(main())

Vlákno asistenta OpenAI

AzureAssistantAgent a OpenAIAssistantAgent používají AssistantAgentThread ke správě historie konverzací a kontextu:

from semantic_kernel.agents import ChatHistoryAgentThread

thread = AssistantAgentThread(
    client: AsyncOpenAI,
    thread_id: str | None = None,
    messages: Iterable["ThreadCreateMessage"] | NotGiven = NOT_GIVEN,
    metadata: dict[str, Any] | NotGiven = NOT_GIVEN,
    tool_resources: ToolResources | NotGiven = NOT_GIVEN,
)

Poskytnutím thread_id se pokračuje v existující konverzaci; pokud tomu tak není, vytvoří se nové vlákno.

Kompletní příklad implementace:

# Copyright (c) Microsoft. All rights reserved.
import asyncio

from semantic_kernel.agents import AzureAssistantAgent


# Simulate a conversation with the agent
USER_INPUTS = [
    "Why is the sky blue?",
    "What is the speed of light?",
    "What have we been talking about?",
]


async def main():
    # 1. Create the client using Azure OpenAI resources and configuration
    client, model = AzureAssistantAgent.setup_resources()

    # 2. Create the assistant on the Azure OpenAI service
    definition = await client.beta.assistants.create(
        model=model,
        instructions="Answer questions about the world in one sentence.",
        name="Assistant",
    )

    # 3. Create a Semantic Kernel agent for the Azure OpenAI assistant
    agent = AzureAssistantAgent(
        client=client,
        definition=definition,
    )

    # 4. Create a new thread for use with the assistant
    # If no thread is provided, a new thread will be
    # created and returned with the initial response
    thread = None

    try:
        for user_input in USER_INPUTS:
            print(f"# User: '{user_input}'")
            # 6. Invoke the agent for the current thread and print the response
            response = await agent.get_response(messages=user_input, thread=thread)
            print(f"# {response.name}: {response}")
            thread = response.thread

    finally:
        # 7. Clean up the resources
        await thread.delete() if thread else None
        await agent.client.beta.assistants.delete(assistant_id=agent.id)


if __name__ == "__main__":
    asyncio.run(main())

Vstupy zpráv pro vyvolání agenta

Předchozí implementace umožňovaly pouze jeden vstup zpráv do metod, jako jsou get_response(...), invoke(...)a invoke_stream(...). Nyní jsme tyto metody aktualizovali tak, aby podporovaly více messages (str | ChatMessageContent | list[str | ChatMessageContent]). Vstupy zpráv musí být předány pomocí argumentu klíčového messages slova, například agent.get_response(messages="user input") nebo agent.invoke(messages="user input").

Metody vyvolání agenta vyžadují aktualizace následujícím způsobem:

Starý způsob

response = await agent.get_response(message="some user input", thread=thread)

Nový způsob

response = await agent.get_response(messages=["some initial inputer", "other input"], thread=thread)

AzureAIAgent

V sémantickém jádru Python 1.26.0+ se teď vytváření vláken AzureAIAgent spravuje prostřednictvím objektu AzureAIAgentThread, ne přímo v klientovi.

Starý způsob

thread = await client.agents.create_thread()

Nový způsob

from semantic_kernel.agents import AzureAIAgentThread

thread = AzureAIAgentThread(
    client: AIProjectClient,  # required
    messages: list[ThreadMessageOptions] | None = None,  # optional
    metadata: dict[str, str] | None = None,  # optional
    thread_id: str | None = None,  # optional
    tool_resources: "ToolResources | None" = None,  # optional
)

Pokud není zpočátku k dispozici žádná thread_id, vytvoří se nové vlákno a to se vrátí v odpovědi agenta.

ChatCompletionAgent

ChatCompletionAgent byla aktualizována, aby zjednodušila konfiguraci služby, zpracování pluginů a chování při volání funkcí. Níže jsou uvedené klíčové změny, které byste měli při migraci zvážit.

1. Určení služby

Nyní můžete službu zadat přímo jako součást konstruktoru agenta:

Nový způsob

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

agent = ChatCompletionAgent(
    service=AzureChatCompletion(),
    name="<name>",
    instructions="<instructions>",
)

Poznámka: Pokud je k dispozici jádro i služba, bude mít tato služba přednost, pokud sdílí stejnou service_id nebo ai_model_id. Jinak pokud jsou samostatné, použije se první služba AI zaregistrovaná v jádru.

Starý způsob (stále platný)

Dříve byste nejprve přidali službu do jádra a pak předali jádro agentovi:

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

kernel = Kernel()
kernel.add_service(AzureChatCompletion())

agent = ChatCompletionAgent(
    kernel=kernel,
    name="<name>",
    instructions="<instructions>",
)

2. Přidání modulů plug-in

Moduly plug-in je teď možné zadat přímo prostřednictvím konstruktoru:

Nový způsob

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

agent = ChatCompletionAgent(
    service=AzureChatCompletion(),
    name="<name>",
    instructions="<instructions>",
    plugins=[SamplePlugin()],
)

Starý způsob (stále platný)

Moduly plug-in dříve musely být přidány do jádra samostatně:

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

kernel = Kernel()
kernel.add_plugin(SamplePlugin())

agent = ChatCompletionAgent(
    kernel=kernel,
    name="<name>",
    instructions="<instructions>",
)

Poznámka: Oba přístupy jsou platné, ale přímé zadávání modulů plug-in zjednodušuje inicializaci.

3. Vyvolání agenta

Teď máte dva způsoby, jak vyvolat agenta. Nová metoda přímo načte jednu odpověď, zatímco stará metoda podporuje streamování.

Nový způsob (bez vlákna konverzace nebo kontextu)

response = await agent.get_response(messages="user input")
# response is of type AgentResponseItem[ChatMessageContent]

Poznámka: Pokud další odpověď nepoužívá vrácené vlákno, konverzace použije nové vlákno, a proto nebude pokračovat s předchozím kontextem.

Nový způsob (jednoduchá odpověď s kontextem)

thread = ChatHistoryAgentThread()

for user_input in ["First user input", "Second User Input"]:
    response = await agent.get_response(messages=user_input, thread=thread)
    # response is of type AgentResponseItem[ChatMessageContent]
    thread = response.thread

Starý způsob (již není platný)

chat_history = ChatHistory()
chat_history.add_user_message("<user_input>")
response = agent.get_response(message="user input", chat_history=chat_history)

4. Řízení volání funkcí

Chování volání funkce lze nyní přímo řídit při specifikaci služby v konstruktoru agenta.

agent = ChatCompletionAgent(
    service=AzureChatCompletion(),
    name="<name>",
    instructions="<instructions>",
    plugins=[MenuPlugin()],
    function_choice_behavior=FunctionChoiceBehavior.Auto(
        filters={"included_functions": ["get_specials", "get_item_price"]}
    ),
)

Poznámka: Dříve nastavení volání funkcí vyžadovalo samostatné nastavení v jádru nebo objektu služby. Pokud nastavení provádění určuje stejné service_id nebo ai_model_id jako konfigurace služby AI, bude mít přednost chování volání funkce definované v nastavení spouštění (prostřednictvím KernelArguments) před chováním funkce nastavené v konstruktoru.

Tyto aktualizace zlepšují jednoduchost a konfigurovatelnost, což usnadňuje integraci a údržbu chatCompletionAgent.

OpenAIAssistantAgent

Změny AzureAssistantAgent a OpenAIAssistantAgent zahrnují aktualizace pro vytváření asistentů, vytváření vláken, zpracování modulů plug-in, používání nástroje pro překlad kódu, práci s nástrojem pro vyhledávání souborů a přidávání chatovacích zpráv do vlákna.

Nastavení zdrojů

Starý způsob

Klient AsyncAzureOpenAI byl vytvořen jako součást vytváření objektu agenta.

agent = await AzureAssistantAgent.create(
    deployment_name="optional-deployment-name",
    api_key="optional-api-key",
    endpoint="optional-endpoint",
    ad_token="optional-ad-token",
    ad_token_provider=optional_callable,
    default_headers={"optional_header": "optional-header-value"},
    env_file_path="optional-env-file-path",
    env_file_encoding="optional-env-file-encoding",
    ...,
)

Nový způsob

Agent poskytuje statickou metodu pro vytvoření požadovaného klienta pro zadané prostředky, kde argumenty klíčových slov na úrovni metody mají přednost před proměnnými prostředí a hodnotami v existujícím souboru .env.

client, model = AzureAssistantAgent.setup_resources(
    ad_token="optional-ad-token",
    ad_token_provider=optional_callable,
    api_key="optional-api-key",
    api_version="optional-api-version",
    base_url="optional-base-url",
    default_headers="optional-default-headers",
    deployment_name="optional-deployment-name",
    endpoint="optional-endpoint",
    env_file_path="optional-env-file-path",
    env_file_encoding="optional-env-file-encoding",
    token_scope="optional-token-scope",
)

1. Vytvoření asistenta

Starý způsob

agent = await AzureAssistantAgent.create(
    kernel=kernel,
    service_id=service_id,
    name=AGENT_NAME,
    instructions=AGENT_INSTRUCTIONS,
    enable_code_interpreter=True,
)

nebo

agent = await OpenAIAssistantAgent.create(
    kernel=kernel,
    service_id=service_id,
    name=<name>,
    instructions=<instructions>,
    enable_code_interpreter=True,
)

Nový způsob

# Azure AssistantAgent 

# Create the client using Azure OpenAI resources and configuration
client, model = AzureAssistantAgent.setup_resources()

# Create the assistant definition
definition = await client.beta.assistants.create(
    model=model,
    instructions="<instructions>",
    name="<name>",
)

# Create the agent using the client and the assistant definition
agent = AzureAssistantAgent(
    client=client,
    definition=definition,
)

nebo

# OpenAI Assistant Agent

# Create the client using OpenAI resources and configuration
client, model = OpenAIAssistantAgent.setup_resources()

# Create the assistant definition
definition = await client.beta.assistants.create(
    model=model,
    instructions="<instructions>",
    name="<name>",
)

# Create the agent using the client and the assistant definition
agent = OpenAIAssistantAgent(
    client=client,
    definition=definition,
)

2. Vytvoření vlákna

Starý způsob

thread_id = await agent.create_thread()

Nový způsob

from semantic_kernel.agents AssistantAgentThread, AzureAssistantAgent

client, model = AzureAssistantAgent.setup_resources()

# You may create a thread based on an existing thread id
# thread = AssistantAgentThread(client=client, thread_id="existing-thread-id")
# Otherwise, if not specified, a thread will be created during the first invocation
# and returned as part of the response
thread = None

async for response in agent.invoke(messages="user input", thread=thread):
    # handle response
    print(response)
    thread = response.thread

3. Zpracování pluginů

Starý způsob

# Create the instance of the Kernel
kernel = Kernel()

# Add the sample plugin to the kernel
kernel.add_plugin(plugin=MenuPlugin(), plugin_name="menu")

agent = await AzureAssistantAgent.create(
    kernel=kernel, 
    name="<name>", 
    instructions="<instructions>"
)

Poznámka: Moduly plug-in je stále možné spravovat prostřednictvím jádra. Pokud nezadáte jádro, jádro se automaticky vytvoří při vytváření agenta a moduly plug-in se do této instance přidají.

Nový způsob

# Create the client using Azure OpenAI resources and configuration
client, model = AzureAssistantAgent.setup_resources()

# Create the assistant definition
definition = await client.beta.assistants.create(
    model=model,
    instructions="<instructions>",
    name="<name>",
)

# Create the agent with plugins passed in as a list
agent = AzureAssistantAgent(
    client=client,
    definition=definition,
    plugins=[MenuPlugin()],
)

Podrobnosti naleznete v ukázkové implementaci .

4. Použití nástroje interpreta kódu

Starý způsob

csv_file_path = ...

agent = await AzureAssistantAgent.create(
    kernel=kernel,
    name="<name>",
    instructions="<instructions>",
    enable_code_interpreter=True,
    code_interpreter_filenames=[csv_file_path],
)

Nový způsob

# Create the client using Azure OpenAI resources and configuration
client, model = AzureAssistantAgent.setup_resources()

csv_file_path = ...

# Load the CSV file as a FileObject
with open(csv_file_path, "rb") as file:
    file = await client.files.create(file=file, purpose="assistants")

# Get the code interpreter tool and resources
code_interpreter_tool, code_interpreter_tool_resource = AzureAssistantAgent.configure_code_interpreter_tool(file.id)

# Create the assistant definition
definition = await client.beta.assistants.create(
    model=model,
    name="<name>",
    instructions="<instructions>.",
    tools=code_interpreter_tool,
    tool_resources=code_interpreter_tool_resource,
)

# Create the AzureAssistantAgent instance using the client and the assistant definition
agent = AzureAssistantAgent(
    client=client,
    definition=definition,
)

Podrobnosti naleznete v ukázkové implementaci .

5. Práce s nástrojem pro vyhledávání souborů

Starý způsob

pdf_file_path = ...

agent = await AzureAssistantAgent.create(
    kernel=kernel,
    service_id=service_id,
    name=AGENT_NAME,
    instructions=AGENT_INSTRUCTIONS,
    enable_file_search=True,
    vector_store_filenames=[pdf_file_path],
)

Nový způsob

# Create the client using Azure OpenAI resources and configuration
client, model = AzureAssistantAgent.setup_resources()

pdf_file_path = ...

# Load the employees PDF file as a FileObject
with open(pdf_file_path, "rb") as file:
    file = await client.files.create(file=file, purpose="assistants")

# Create a vector store specifying the file ID to be used for file search
vector_store = await client.beta.vector_stores.create(
    name="step4_assistant_file_search",
    file_ids=[file.id],
)

file_search_tool, file_search_tool_resources = AzureAssistantAgent.configure_file_search_tool(vector_store.id)

# Create the assistant definition
definition = await client.beta.assistants.create(
    model=model,
    instructions="Find answers to the user's questions in the provided file.",
    name="FileSearch",
    tools=file_search_tool,
    tool_resources=file_search_tool_resources,
)

# Create the AzureAssistantAgent instance using the client and the assistant definition
agent = AzureAssistantAgent(
    client=client,
    definition=definition,
)

Podrobnosti naleznete v ukázkové implementaci .

6. Přidání chatových zpráv do vlákna

Starý způsob

await agent.add_chat_message(
    thread_id=thread_id, 
    message=ChatMessageContent(role=AuthorRole.USER, content=user_input)
)

Nový způsob

Poznámka: Stará metoda stále funguje, pokud předáte ChatMessageContent, ale nyní můžete také předat jednoduchý řetězec.

await agent.add_chat_message(
    thread_id=thread_id, 
    message=user_input,
)

7. Vyčištění prostředků

Starý způsob

await agent.delete_file(file_id)
await agent.delete_thread(thread_id)
await agent.delete()

Nový způsob

await client.files.delete(file_id)
await thread.delete()
await client.beta.assistants.delete(agent.id)

Zpracování strukturovaných výstupů

Starý způsob

Nedostupné starým způsobem

Nový způsob

# Define a Pydantic model that represents the structured output from the OpenAI service
class ResponseModel(BaseModel):
    response: str
    items: list[str]

# Create the client using Azure OpenAI resources and configuration
client, model = AzureAssistantAgent.setup_resources()

# Create the assistant definition
definition = await client.beta.assistants.create(
    model=model,
    name="<name>",
    instructions="<instructions>",
    response_format=AzureAssistantAgent.configure_response_format(ResponseModel),
)

# Create the AzureAssistantAgent instance using the client and the assistant definition
agent = AzureAssistantAgent(
    client=client,
    definition=definition,
)

Podrobnosti naleznete v ukázkové implementaci .

Tento průvodce migrací by vám měl pomoct s aktualizací kódu na novou implementaci, využití konfigurace na základě klienta a vylepšených funkcí.

Agenti nejsou v Javě k dispozici.