Guide de migration de la version candidate d'Agent Framework

API d’appel d’agent commun

Dans la version 1.43.0, nous publions une nouvelle API d’appel d’agent commune, qui permettra à tous les types d’agents d’être appelés via une API commune.

Pour activer cette nouvelle API, nous introduisons le concept d'un AgentThread, qui représente un fil de conversation et abstrait les différentes exigences de gestion des fils pour différents types d'agents. Pour certains types d’agents, il permettra également à l’avenir d’utiliser différentes implémentations de threads avec le même agent.

Les méthodes courantes Invoke que nous introduisons vous permettent de fournir les messages que vous souhaitez transmettre à l’agent et un message facultatif AgentThread. Si un AgentThread est fourni, cela continuera la conversation déjà en cours sur le AgentThread. Si aucun AgentThread n’est fourni, un nouveau fil par défaut sera créé et renvoyé dans la réponse.

Il est également possible de créer manuellement une AgentThread instance, par exemple dans les cas où vous pouvez avoir un ID de thread à partir du service d’agent sous-jacent et que vous souhaitez continuer ce thread. Vous pouvez également personnaliser les options du thread, par exemple les outils associés.

Voici un exemple simple de la façon dont n’importe quel agent peut désormais être utilisé avec du code indépendant de l’agent.

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

Ces modifications ont été appliquées dans :

• PR #11116

Options de thread de l’agent Azure AI

Actuellement, le AzureAIAgent prend uniquement en charge les fils de type AzureAIAgentThread.

En plus d’autoriser la création automatique d’un thread sur l’appel de l’agent, vous pouvez également construire manuellement une instance d’un AzureAIAgentThread.

AzureAIAgentThread peut être créé avec des outils et des métadonnées personnalisés, ainsi qu’avec des messages pour amorcer la conversation.

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

Vous pouvez également construire une instance de AzureAIAgentThread qui poursuit une conversation existante.

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

Options de thread de l’agent Bedrock

Actuellement, le BedrockAgent prend uniquement en charge les fils de type BedrockAgentThread.

En plus d’autoriser la création automatique d’un thread sur l’appel de l’agent, vous pouvez également construire manuellement une instance d’un BedrockAgentThread.

AgentThread thread = new BedrockAgentThread(amazonBedrockAgentRuntimeClient);

Vous pouvez également construire une instance de BedrockAgentThread qui poursuit une conversation existante.

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

Options de fil de l’agent de complétion de chat

Actuellement, le ChatCompletionAgent prend uniquement en charge les fils de type ChatHistoryAgentThread. ChatHistoryAgentThread utilise un objet en mémoire ChatHistory pour stocker les messages sur le thread.

En plus d’autoriser la création automatique d’un thread sur l’appel de l’agent, vous pouvez également construire manuellement une instance d’un ChatHistoryAgentThread.

AgentThread thread = new ChatHistoryAgentThread();

Vous pouvez également construire une instance d’un ChatHistoryAgentThread pour continuer une conversation existante en transmettant un objet ChatHistory avec les messages déjà présents.

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

AgentThread thread = new ChatHistoryAgentThread(chatHistory: chatHistory);

Options de thread de l’Assistant OpenAI

Actuellement, le OpenAIAssistantAgent prend uniquement en charge les fils de type OpenAIAssistantAgentThread.

En plus d’autoriser la création automatique d’un thread sur l’appel de l’agent, vous pouvez également construire manuellement une instance d’un OpenAIAssistantAgentThread.

OpenAIAssistantAgentThread peut être créé avec des outils et des métadonnées personnalisés, ainsi que des messages pour initialiser la conversation.

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

Vous pouvez également construire une instance de OpenAIAssistantAgentThread qui poursuit une conversation existante.

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

OpenAIAssistantAgent C# Migration Guide

Nous avons récemment mis en œuvre un changement significatif concernant le OpenAIAssistantAgent dans le framework pour l'agent Kernel sémantique.

Ces modifications ont été appliquées dans :

• PR #10583
• PR #10616
• PR #10633

Ces modifications sont destinées à :

• Aligner avec le modèle à utiliser pour notre AzureAIAgent.
• Corrigez les bogues liés au modèle d’initialisation statique.
• Évitez de limiter les fonctionnalités en fonction de notre abstraction du Kit de développement logiciel (SDK) sous-jacent.

Ce guide fournit des instructions pas à pas pour migrer votre code C# de l’ancienne implémentation vers la nouvelle. Les modifications incluent des mises à jour pour la création d’assistants, la gestion du cycle de vie de l’Assistant, la gestion des threads, des fichiers et des magasins vectoriels.

1. Création d’une instance client

Auparavant, OpenAIClientProvider était nécessaire pour créer n’importe quel OpenAIAssistantAgent. Cette dépendance a été simplifiée.

Nouvelle façon

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

Old Way (déconseillé)

var clientProvider = new OpenAIClientProvider(...);

2. Cycle de vie de l’Assistant

Création d’un Assistant

Vous pouvez maintenant instancier directement un OpenAIAssistantAgent à l'aide d'une définition d'Assistant existante ou nouvelle depuis AssistantClient.

Nouvelle façon

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

Les plug-ins peuvent être directement inclus lors de l’initialisation :

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

Création d’une définition d’assistant à l’aide d’une méthode d’extension :

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

Old Way (déconseillé)

Auparavant, les définitions d’assistant étaient gérées indirectement.

3. Invoquer l'Agent

Vous pouvez spécifier RunCreationOptions directement, en activant l’accès complet aux fonctionnalités du Kit de développement logiciel (SDK) sous-jacentes.

Nouvelle façon

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

Old Way (déconseillé)

var options = new OpenAIAssistantInvocationOptions();

4. Suppression de l’Assistant

Vous pouvez gérer directement la suppression de l’Assistant avec AssistantClient.

await assistantClient.DeleteAssistantAsync(agent.Id);

5. Cycle de vie du fil

Création d’un thread

Les threads sont désormais gérés via AssistantAgentThread.

Nouvelle façon

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

Old Way (déconseillé)

Auparavant, la gestion des threads était indirecte ou liée à l’agent.

Suppression de threads

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

6. Cycle de vie des fichiers

La création et la suppression de fichiers utilisent OpenAIFileClientdésormais .

Chargement de fichiers

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

Suppression de fichiers

await client.DeleteFileAsync(fileId);

7. Cycle de vie du stockage vectoriel

Les magasins vectoriels sont gérés directement par le biais de VectorStoreClient, avec des méthodes d'extension pratiques.

Création d’une base de vecteurs

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

Suppression de la base de données vectorielle

await client.DeleteVectorStoreAsync(vectorStoreId);

Compatibilité rétroactive

Les modèles déconseillés sont marqués avec [Obsolete]. Pour supprimer les avertissements obsolètes (CS0618), mettez à jour votre fichier projet comme suit :

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

Ce guide de migration vous permet de passer en douceur à la nouvelle implémentation, en simplifiant l’initialisation du client, la gestion des ressources et l’intégration avec le SDK .NET du noyau sémantique.

Ces modifications ont été appliquées dans :

• PR #11116

Les modifications précédentes ont été appliquées dans :

• PR #10666
• PR #10667
• PR #10701
• PR #10707

Ce guide fournit des instructions pas à pas pour migrer votre code Python de l’ancienne implémentation vers la nouvelle implémentation.

Importations de l’agent

Tous les chemins d’importation de l’agent ont été consolidés sous semantic_kernel.agents.

Style d’importation mis à jour

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

Style d’importation précédent (déconseillé) :

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

API d’appel d’agent commun

À partir du noyau sémantique Python 1.26.0 et versions ultérieures, nous avons introduit une nouvelle abstraction commune pour gérer les threads pour tous les agents. Pour chaque agent, nous exposons désormais une classe de thread qui implémente la classe de base, permettant la gestion du contexte via des méthodes telles que AgentThread et create().

Les réponses get_response(...) de l’agent, invoke(...), invoke_stream(...) retournent maintenant un AgentResponseItem[ChatMessageContent], qui ont deux attributs :

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

Ajout de messages à un thread

Les messages doivent être ajoutés à un thread via l’argument messages dans le cadre des méthodes get_response(...), invoke(...) ou invoke_stream(...) de l’agent.

Fil de l’agent Azure AI

Vous pouvez créer une AzureAIAgentThread valeur comme suit :

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
)

La fourniture d’une thread_id (chaîne) vous permet de poursuivre une conversation existante. S’il est omis, un nouveau fil est créé et renvoyé dans la réponse de l’agent.

Exemple d’implémentation complet :

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

Thread de l’agent Bedrock

A BedrockAgent utilise un BedrockAgentThread pour gérer l’historique et le contexte des conversations. Vous pouvez fournir un session_id pour continuer une conversation existante ou en initier une nouvelle.

from semantic_kernel.agents import BedrockAgentThread

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

Si aucun session_id n'est fourni, un nouveau contexte est créé automatiquement.

Exemple d’implémentation complet :

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

Fil de discussion de l'agent - Historique des conversations

ChatCompletionAgent utilise ChatHistoryAgentThread pour gérer l’historique des conversations. Il peut être initialisé comme suit :

from semantic_kernel.agents import ChatHistoryAgentThread

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

Fournir un thread_id permet de poursuivre les conversations existantes. Omettre cela crée un nouveau thread. La sérialisation et la réactivation de l’état du thread sont prises en charge pour les contextes de conversation persistants.

Exemple d’implémentation complet :

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

Fil de l’assistant OpenAI

Les AzureAssistantAgent et OpenAIAssistantAgent utilisent AssistantAgentThread pour gérer l’historique des conversations et le contexte.

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

Fournir un thread_id permet de poursuivre une conversation existante ; sinon, un nouveau fil est créé.

Exemple d’implémentation complet :

# 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())

Entrées de message pour l’appel de l’agent

Les implémentations précédentes n’ont autorisé qu’une seule entrée de message à des méthodes telles que get_response(...), invoke(...)et invoke_stream(...). Nous avons maintenant mis à jour ces méthodes pour prendre en charge plusieurs messages (str | ChatMessageContent | list[str | ChatMessageContent]). Les entrées de message doivent être transmises avec l’argument messages de mot clé, tel que agent.get_response(messages="user input") ou agent.invoke(messages="user input").

Les méthodes d’appel d’agent ont besoin de mises à jour comme suit :

Ancienne Méthode

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

Nouvelle façon

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

AzureAIAgent

Dans Le noyau sémantique Python 1.26.0+, la AzureAIAgent création de threads est désormais gérée via l’objet AzureAIAgentThread , et non directement sur le client.

Ancienne Méthode

thread = await client.agents.create_thread()

Nouvelle façon

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
)

Si aucun thread_id n'est fourni initialement, un nouveau thread est créé et retourné dans la réponse de l’agent.

ChatCompletionAgent

Le ChatCompletionAgent a été mis à jour pour simplifier la configuration du service, la gestion des plugins et les processus d’appel de fonction. Voici les principales modifications que vous devez prendre en compte lors de la migration.

1. Spécification du service

Vous pouvez maintenant spécifier le service directement dans le cadre du constructeur de l’agent :

Nouvelle façon

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

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

Remarque : Si un noyau et un service sont fournis, le service est prioritaire s’il partage la même service_id ou ai_model_id. Sinon, s’ils sont séparés, le premier service IA inscrit sur le noyau sera utilisé.

Old Way (toujours valide)

Auparavant, vous ajoutez d’abord un service à un noyau, puis transmettez le noyau à l’agent :

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. Ajout de plug-ins

Les plug-ins peuvent désormais être fournis directement via le constructeur :

Nouvelle façon

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

Old Way (toujours valide)

Auparavant, les plug-ins devaient être ajoutés au noyau séparément :

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

Remarque : les deux approches sont valides, mais la spécification directe de plug-ins simplifie l’initialisation.

3. Invoquer l'Agent

Vous disposez maintenant de deux façons d’appeler l’agent. La nouvelle méthode récupère directement une seule réponse, tandis que l’ancienne méthode prend en charge la diffusion en continu.

Nouvelle façon (pas de fil de discussion/contexte)

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

Remarque : si la réponse suivante n’utilise pas le thread retourné, la conversation utilise un nouveau thread et ne continuera donc pas avec le contexte précédent.

New Way (réponse unique avec contexte)

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

Old Way (non valide)

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

4. Contrôle de l'appel de fonction

Le comportement d’appel de fonction peut désormais être contrôlé directement lors de la spécification du service dans le constructeur de l’agent :

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

Remarque : Auparavant, la configuration d’appel de fonction nécessitait une configuration distincte sur le noyau ou l’objet de service. Si les paramètres d’exécution spécifient le même service_id ou ai_model_id que la configuration du service IA, le comportement d’appel de fonction défini dans les paramètres d’exécution (via KernelArguments) est prioritaire sur le comportement de choix de fonction défini dans le constructeur.

Ces mises à jour améliorent la simplicité et la configuration, ce qui facilite l’intégration et la maintenance de ChatCompletionAgent.

OpenAIAssistantAgent

Les modifications apportées à AzureAssistantAgent et à OpenAIAssistantAgent incluent des mises à jour concernant la création d’assistants, la création de fils de discussion, la gestion des extensions, l’utilisation de l’outil d’interprétation de code, l’utilisation de l’outil de recherche de fichiers et l’ajout de messages de chat à un fil de discussion.

Configuration des ressources

Ancienne Méthode

Le AsyncAzureOpenAI client a été créé dans le cadre de la création de l’objet Agent.

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

Nouvelle façon

L’agent fournit une méthode statique pour créer le client requis pour les ressources spécifiées, où les arguments de mot clé au niveau de la méthode sont prioritaires sur les variables et valeurs d’environnement dans un fichier existant .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. Création d’un Assistant

Ancienne Méthode

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

or

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

Nouvelle façon

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

or

# 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. Création d’un thread

Ancienne Méthode

thread_id = await agent.create_thread()

Nouvelle façon

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. Gestion des plug-ins

Ancienne Méthode

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

Remarque : Il est toujours possible de gérer les plug-ins via le noyau. Si vous ne fournissez pas de noyau, un noyau est automatiquement créé au moment de la création de l’agent et les plug-ins sont ajoutés à cette instance.

Nouvelle façon

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

Pour plus d’informations, reportez-vous à l’exemple d’implémentation .

4. Utilisation de l’outil Interpréteur de code

Ancienne Méthode

csv_file_path = ...

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

Nouvelle façon

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

Pour plus d’informations, reportez-vous à l’exemple d’implémentation .

5. Utilisation de l’outil de recherche de fichiers

Ancienne Méthode

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

Nouvelle façon

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

Pour plus d’informations, reportez-vous à l’exemple d’implémentation .

6. Ajout de messages de conversation à un thread

Ancienne Méthode

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

Nouvelle façon

Remarque : L’ancienne méthode fonctionne toujours si vous passez un ChatMessageContent, mais vous pouvez désormais également passer une chaîne simple.

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

7. Nettoyage des ressources

Ancienne Méthode

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

Nouvelle façon

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

Gestion des sorties structurées

Ancienne Méthode

Non disponible dans l’ancien chemin

Nouvelle façon

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

Pour plus d’informations, reportez-vous à l’exemple d’implémentation .

Ce guide de migration doit vous aider à mettre à jour votre code vers la nouvelle implémentation, en tirant parti de la configuration basée sur le client et des fonctionnalités améliorées.

Les agents ne sont pas disponibles dans Java.