Sdílet prostřednictvím

Zkoumání sémantického jádra OpenAIAssistantAgent

Důležité

Funkce s jedním agentem, například OpenAIAssistantAgent, jsou ve fázi kandidáta na vydání. Tyto funkce jsou téměř úplné a obecně stabilní, i když mohou před dosažením úplné obecné dostupnosti projít dílčími vylepšeními nebo optimalizacemi.

Návod

Podrobná dokumentace k rozhraní API související s touto diskuzí je k dispozici na adrese:

Návod

Podrobná dokumentace k rozhraní API související s touto diskuzí je k dispozici na adrese:

Funkce aktuálně není dostupná v Javě.

Co je asistent?

Rozhraní API pro pomocníky OpenAI je specializované rozhraní navržené pro pokročilejší a interaktivní funkce AI, které vývojářům umožňují vytvářet přizpůsobené a vícekrokové agenty orientované na úlohy. Na rozdíl od rozhraní API pro dokončování chatu, které se zaměřuje na jednoduché konverzační výměny, umožňuje rozhraní API pomocníka dynamické interakce řízené cíli s dalšími funkcemi, jako je interpret kódu a vyhledávání souborů.

Příprava vývojového prostředí

Pokud chcete pokračovat v vývoji OpenAIAssistantAgent, nakonfigurujte vývojové prostředí s příslušnými balíčky.

Přidejte do projektu balíček Microsoft.SemanticKernel.Agents.OpenAI:

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

Můžete také zahrnout balíček Azure.Identity:

dotnet add package Azure.Identity

Nainstalujte balíček semantic-kernel:

pip install semantic-kernel

Funkce aktuálně není dostupná v Javě.

Vytvoření OpenAIAssistantAgent

Vytvoření OpenAIAssistant vyžaduje nejprve vytvoření klienta, aby bylo možné komunikovat se vzdálenou službou.

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

Funkce aktuálně není dostupná v Javě.

Načítání OpenAIAssistantAgent

Po vytvoření může být identifikátor asistenta přístupný prostřednictvím jeho identifikátoru. Tento identifikátor lze použít k vytvoření OpenAIAssistantAgent z existující definice asistenta.

Pro .NET je identifikátor agenta vystaven jako string prostřednictvím vlastnosti definované libovolným agentem.

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

Funkce aktuálně není dostupná v Javě.

Použití OpenAIAssistantAgent

Stejně jako u všech aspektů rozhraní API pomocníka se konverzace ukládají vzdáleně. Každá konverzace se označuje jako vlákno a identifikuje se jedinečným string identifikátorem. Interakce s vaším OpenAIAssistantAgent jsou svázané s tímto konkrétním identifikátorem vlákna. Specifika vlákna API asistenta se abstrahují prostřednictvím třídy OpenAIAssistantAgentThread, která implementuje AgentThread.

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

Můžete vyvolat OpenAIAssistantAgent bez zadání AgentThreadke spuštění nového vlákna, a nový AgentThread bude vrácen jako součást odpovědi.


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

Můžete také vyvolat OpenAIAssistantAgent pomocí AgentThread, který jste vytvořili.

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

Můžete také vytvořit OpenAIAssistantAgentThread, která obnoví dřívější konverzaci podle 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

Funkce aktuálně není dostupná v Javě.

Odstranění jednoho OpenAIAssistantAgent

Vzhledem k tomu, že definice asistenta je uložená vzdáleně, zůstane v případě, že se neodstraní.
Odstranění definice asistenta může být provedeno přímo s klientem.

Poznámka: Při pokusu o použití instance agenta po odstranění dojde k výjimce služby.

Pro .NET je identifikátor agenta vystaven jako string prostřednictvím Agent.Id vlastnosti definované libovolným agentem.

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

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

Funkce aktuálně není dostupná v Javě.

Zpracování přechodných zpráv pomocí OpenAIAssistantAgent

Sémantické jádro OpenAIAssistantAgent je navrženo tak, aby použilo agenta, který zodpovídá dotazy nebo otázky uživatelů. Během vyvolání může agent spouštět nástroje, které odvozují konečnou odpověď. Pro přístup k přechodným zprávám vytvořeným během tohoto procesu mohou volající poskytnout funkci zpětného volání, která zpracovává instance FunctionCallContent nebo FunctionResultContent.

Dokumentace ke zpětnému volání pro tuto OpenAIAssistantAgent bude dostupná brzy.

Konfigurace zpětného on_intermediate_message volání uvnitř agent.invoke(...) nebo agent.invoke_stream(...) umožňuje volajícímu přijímat přechodné zprávy generované během procesu formulace konečné odpovědi agenta.

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

Následující příklad ukazuje ukázkový výstup z procesu vyvolání agenta:

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!

Funkce aktuálně není dostupná v Javě.

Deklarativní specifikace

Dokumentace k používání deklarativních specifikací bude brzy k dispozici.

Důležité

Tato funkce je v experimentální fázi. Funkce v této fázi jsou ve vývoji a před přechodem na fázi Preview nebo release candidate se můžou změnit.

Podporování instancí z deklarativní specifikace YAML pomocí OpenAIAssistantAgent. Deklarativní přístup umožňuje definovat vlastnosti, pokyny, konfiguraci modelu, nástroje a další možnosti v jednom auditovatelném dokumentu. Díky tomu je složení agentů přenosné a snadno spravované napříč prostředími.

Poznámka:

Všechny nástroje, funkce nebo moduly plug-in uvedené v deklarativním jazyce YAML musí být k dispozici agentovi v době výstavby. U modulů plug-in založených na jádru to znamená, že musí být zaregistrované v jádru. Pro integrované nástroje, jako je interpret kódu nebo vyhledávání souborů, musí být zadána správná konfigurace a přihlašovací údaje. Zavaděč agenta nebude vytvářet funkce z ničeho. Pokud chybí požadovaná komponenta, vytvoření agenta selže.

Jak používat deklarativní specifikaci

Místo vytvoření výčtu všech možných konfigurací YAML tato část popisuje klíčové principy a poskytuje odkazy na ukázky konceptů, které zobrazují kompletní kód pro každý typ nástroje. Projděte si tyto ukázky konceptů OpenAIAssistantAgent pro komplexní implementace deklarativních specifikací:

AzureAssistantAgent vzorky:

OpenAIAssistantAgent vzorky:

Příklad: Vytvoření agenta AzureAIAgent z YAML

Minimální deklarativní specifikace YAML může vypadat takto:

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

Podrobnosti o tom, jak připojit agenta, najdete v kompletních ukázkách kódu výše.

Klíčové body

  • Deklarativní specifikace umožňují definovat strukturu agenta, nástroje a chování v YAML.
  • Všechny odkazované nástroje a moduly plug-in musí být zaregistrované nebo přístupné za běhu.
  • Integrované nástroje, jako je Bing, Vyhledávání souborů a interpret kódu, vyžadují správnou konfiguraci a přihlašovací údaje (často prostřednictvím proměnných prostředí nebo explicitních argumentů).
  • Komplexní příklady najdete na uvedených ukázkových odkazech, které demonstrují praktické scénáře, včetně registrace modulu plug-in, konfigurace identity Azure a pokročilého použití nástrojů.

Tato funkce není k dispozici.

Návod

Kompletní příklad od začátku do konce pro OpenAIAssistantAgent najdete zde:

Další kroky

Prozkoumání agenta odpovědí OpenAI