Exploration du noyau sémantique OpenAIAssistantAgent

Fonctionnalité actuellement indisponible en Java.

Ajoutez le package Microsoft.SemanticKernel.Agents.OpenAI à votre projet :

dotnet add package Microsoft.SemanticKernel.Agents.OpenAI --prerelease

Vous pouvez également inclure le package Azure.Identity :

dotnet add package Azure.Identity

Installez le package semantic-kernel :

pip install semantic-kernel

Fonctionnalité actuellement indisponible en Java.

AssistantClient client = OpenAIAssistantAgent.CreateAzureOpenAIClient(...).GetAssistantClient();
Assistant assistant =
    await client.CreateAssistantAsync(
        "<model name>",
        "<agent name>",
        instructions: "<agent instructions>");
OpenAIAssistantAgent agent = new(assistant, client);

from semantic_kernel.agents import AssistantAgentThread, AzureAssistantAgent, OpenAIAssistantAgent
from semantic_kernel.connectors.ai.open_ai import AzureOpenAISettings, OpenAISettings

# Set up the client and model using Azure OpenAI Resources
client = AzureAssistantAgent.create_client()

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

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

# or

# Set up the client and model using OpenAI Resources
client = OpenAIAssistantAgent.create_client()

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

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

Fonctionnalité actuellement indisponible en Java.

Pour .NET, l’identificateur de l’agent est exposé sous la forme d’une string propriété définie par n’importe quel agent.

AssistantClient client = OpenAIAssistantAgent.CreateAzureOpenAIClient(...).GetAssistantClient();
Assistant assistant = await client.GetAssistantAsync("<assistant id>");
OpenAIAssistantAgent agent = new(assistant, client);

# Using Azure OpenAI Resources

# Create the client using Azure OpenAI resources and configuration
client = AzureAssistantAgent.create_client()

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

# Store the assistant ID
assistant_id = definition.id

# Retrieve the assistant definition from the server based on the assistant ID
new_asst_definition = await client.beta.assistants.retrieve(assistant_id)

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

Fonctionnalité actuellement indisponible en Java.

// Define agent
OpenAIAssistantAgent agent = ...;
AgentThread? agentThread = null;

// Generate the agent response(s)
await foreach (AgentResponseItem<ChatMessageContent> response in agent.InvokeAsync(new ChatMessageContent(AuthorRole.User, "<user input>")))
{
  // Process agent response(s)...
  agentThread = response.Thread;
}

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

Vous pouvez également invoquer le OpenAIAssistantAgent avec un AgentThread que vous avez créé.

// Define agent
OpenAIAssistantAgent agent = ...;

// Create a thread with some custom metadata.
AgentThread agentThread = new OpenAIAssistantAgentThread(client, metadata: myMetadata);

// Generate the agent response(s)
await foreach (ChatMessageContent response in agent.InvokeAsync(new ChatMessageContent(AuthorRole.User, "<user input>"), agentThread))
{
  // Process agent response(s)...
}

// Delete the thread when it is no longer needed
await agentThread.DeleteAsync();

Vous pouvez également créer un OpenAIAssistantAgentThread élément qui reprend une conversation antérieure par ID.

// Create a thread with an existing thread id.
AgentThread agentThread = new OpenAIAssistantAgentThread(client, "existing-thread-id");

from semantic_kernel.agents import AssistantAgentThread, AzureAssistantAgent

# Define agent
openai_agent = await ...

# Create a thread for the agent conversation
thread: AssistantAgentThread = None

# Generate the agent response(s)
async for response in agent.invoke(messages="user input", thread=thread):
  # process agent response(s)...
  thread = response.thread

# Delete the thread when it is no longer needed
await thread.delete() if thread else None

Fonctionnalité actuellement indisponible en Java.

Pour .NET, l’identificateur de l’agent est exposé sous la forme d’une stringAgent.Id propriété définie par n’importe quel agent.

AssistantClient client = OpenAIAssistantAgent.CreateAzureOpenAIClient(...).GetAssistantClient();
await client.DeleteAssistantAsync("<assistant id>");

await client.beta.assistants.delete(agent.id)

Fonctionnalité actuellement indisponible en Java.

La documentation du callback pour OpenAIAssistantAgent sera bientôt disponible.

La configuration du on_intermediate_message rappel dans agent.invoke(...) ou agent.invoke_stream(...) permet à l’appelant de recevoir des messages intermédiaires générés pendant le processus de formulation de la réponse finale de l’agent.

import asyncio
from typing import Annotated

from semantic_kernel.agents import AssistantAgentThread, AzureAssistantAgent
from semantic_kernel.connectors.ai.open_ai import AzureOpenAISettings
from semantic_kernel.contents import AuthorRole, ChatMessageContent, FunctionCallContent, FunctionResultContent
from semantic_kernel.functions import kernel_function


# Define a sample plugin for the sample
class MenuPlugin:
    """A sample Menu Plugin used for the concept sample."""

    @kernel_function(description="Provides a list of specials from the menu.")
    def get_specials(self) -> Annotated[str, "Returns the specials from the menu."]:
        return """
        Special Soup: Clam Chowder
        Special Salad: Cobb Salad
        Special Drink: Chai Tea
        """

    @kernel_function(description="Provides the price of the requested menu item.")
    def get_item_price(
        self, menu_item: Annotated[str, "The name of the menu item."]
    ) -> Annotated[str, "Returns the price of the menu item."]:
        return "$9.99"


# This callback function will be called for each intermediate message,
# which will allow one to handle FunctionCallContent and FunctionResultContent.
# If the callback is not provided, the agent will return the final response
# with no intermediate tool call steps.
async def handle_intermediate_steps(message: ChatMessageContent) -> None:
    for item in message.items or []:
        if isinstance(item, FunctionResultContent):
            print(f"Function Result:> {item.result} for function: {item.name}")
        elif isinstance(item, FunctionCallContent):
            print(f"Function Call:> {item.name} with arguments: {item.arguments}")
        else:
            print(f"{item}")


async def main():
    # Create the client using Azure OpenAI resources and configuration
    client = AzureAssistantAgent.create_client()

    # Define the assistant definition
    definition = await client.beta.assistants.create(
        model=AzureOpenAISettings().chat_deployment_name,
        name="Host",
        instructions="Answer questions about the menu.",
    )

    # Create the AzureAssistantAgent instance using the client and the assistant definition and the defined plugin
    agent = AzureAssistantAgent(
        client=client,
        definition=definition,
        plugins=[MenuPlugin()],
    )

    # 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: AssistantAgentThread = None

    user_inputs = [
        "Hello",
        "What is the special soup?",
        "What is the special drink?",
        "How much is that?",
        "Thank you",
    ]

    try:
        for user_input in user_inputs:
            print(f"# {AuthorRole.USER}: '{user_input}'")
            async for response in agent.invoke(
                messages=user_input,
                thread=thread,
                on_intermediate_message=handle_intermediate_steps,
            ):
                print(f"# {response.role}: {response}")
                thread = response.thread
    finally:
        await thread.delete() if thread else None
        await client.beta.assistants.delete(assistant_id=agent.id)


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

Voici un exemple de résultat du processus d'invocation de l'agent :

AuthorRole.USER: 'Hello'
AuthorRole.ASSISTANT: Hello! How can I assist you today?
AuthorRole.USER: 'What is the special soup?'
Function Call:> MenuPlugin-get_specials with arguments: {}
Function Result:> 
        Special Soup: Clam Chowder
        Special Salad: Cobb Salad
        Special Drink: Chai Tea
        for function: MenuPlugin-get_specials
AuthorRole.ASSISTANT: The special soup is Clam Chowder. Would you like to know more about the specials or 
    anything else?
AuthorRole.USER: 'What is the special drink?'
AuthorRole.ASSISTANT: The special drink is Chai Tea. If you have any more questions, feel free to ask!
AuthorRole.USER: 'How much is that?'
Function Call:> MenuPlugin-get_item_price with arguments: {"menu_item":"Chai Tea"}
Function Result:> $9.99 for function: MenuPlugin-get_item_price
AuthorRole.ASSISTANT: The Chai Tea is priced at $9.99. If there's anything else you'd like to know, 
    just let me know!
AuthorRole.USER: 'Thank you'
AuthorRole.ASSISTANT: You're welcome! If you have any more questions or need further assistance, feel free to 
    ask. Enjoy your day!

Fonctionnalité actuellement indisponible en Java.

La documentation sur l’utilisation de spécifications déclaratives sera bientôt disponible.

OpenAIAssistantAgent prend en charge l'instanciation à partir d'une spécification déclarative YAML. L’approche déclarative vous permet de définir les propriétés, instructions, configuration du modèle, outils et autres options de l’agent dans un document unique et auditable. Cela rend la composition de l’agent portable et facilement gérée dans les environnements.

Guide pratique pour utiliser la spécification déclarative

Au lieu d’énumérer toutes les configurations YAML possibles, cette section décrit les principes clés et fournit des liens vers des exemples de concept qui montrent le code complet pour chaque type d’outil. Reportez-vous à ces échantillons de concepts pour des implémentations de bout en bout d'un OpenAIAssistantAgent avec des spécifications déclaratives.

AzureAssistantAgent Échantillons:

• Interpréteur de code
• Recherche de fichiers
• Plug-in de fonction à partir d’un fichier
• Charger à partir de l’ID d’Assistant existant
• Modèle de requête

OpenAIAssistantAgent Échantillons:

• Interpréteur de code
• Recherche de fichiers
• Plug-in de fonction
• Plug-in de fonction à partir d’un fichier
• Charger à partir de l’ID d’Assistant existant
• Modèle de requête

Exemple : création d’une instance AzureAIAgent à partir de YAML

Une spécification déclarative YAML minimale peut ressembler à ce qui suit :

type: openai_assistant
name: Host
instructions: Respond politely to the user's questions.
model:
  id: ${OpenAI:ChatModelId}
tools:
  - id: MenuPlugin.get_specials
    type: function
  - id: MenuPlugin.get_item_price
    type: function

Pour plus d’informations sur la façon de connecter l’agent, reportez-vous aux exemples de code complets ci-dessus.

Points clés

• Les spécifications déclaratives permettent de définir la structure, les outils et le comportement de l’agent dans YAML.
• Tous les outils et plug-ins référencés doivent être inscrits ou accessibles au moment de l’exécution.
• Les outils intégrés tels que Bing, Recherche de fichiers et Interpréteur de code nécessitent une configuration et des informations d’identification appropriées (souvent par le biais de variables d’environnement ou d’arguments explicites).
• Pour obtenir des exemples complets, consultez les exemples de liens fournis qui illustrent des scénarios pratiques, notamment l’inscription de plug-in, la configuration des identités Azure et l’utilisation d’outils avancés.

Cette fonctionnalité n’est pas disponible.