A Szemantikus Kernel OpenAIAssistantAgent felfedezése

Fontos

Az együgynök-funkciók, például OpenAIAssistantAgenta kiadásra jelölt fázisban vannak. Ezek a funkciók szinte teljesek és általában stabilak, bár kisebb finomításokon vagy optimalizálásokon eshetnek át, mielőtt elérnék a teljes általános rendelkezésre állást.

Jótanács

A jelen vitafórumhoz kapcsolódó részletes API-dokumentáció a következő címen érhető el:

Jótanács

A jelen vitafórumhoz kapcsolódó részletes API-dokumentáció a következő címen érhető el:

A funkció jelenleg nem érhető el a Javában.

Mi az asszisztens?

Az OpenAI Assistants API egy speciális felület, amelyet fejlettebb és interaktívabb AI-képességekre terveztek, így a fejlesztők személyre szabott és többlépéses feladatorientált ügynököket hozhatnak létre. A Csevegés befejezése API-val ellentétben, amely az egyszerű beszélgetési csereprogramokra összpontosít, az Assistant API dinamikus, célvezérelt interakciókat tesz lehetővé további funkciókkal, például kódértelmezővel és fájlkereséssel.

A fejlesztési környezet előkészítése

A OpenAIAssistantAgentfejlesztésének folytatásához konfigurálja a fejlesztői környezetet a megfelelő csomagokkal.

Adja hozzá a Microsoft.SemanticKernel.Agents.OpenAI csomagot a projekthez:

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

Érdemes fontolóra venni a Azure.Identity csomag beillesztését is:

dotnet add package Azure.Identity

Telepítse a semantic-kernel csomagot:

pip install semantic-kernel

A funkció jelenleg nem érhető el a Javában.

Egy OpenAIAssistantAgent létrehozása

Egy OpenAIAssistant létrehozásához először létre kell hoznia egy ügyfelet, amely képes kommunikálni egy távoli szolgáltatással.

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

A funkció jelenleg nem érhető el a Javában.

OpenAIAssistantAgent lekérése

A létrehozás után az asszisztens azonosítója az azonosítón keresztül érhető el. Ezzel az azonosítóval létrehozhat egy OpenAIAssistantAgent egy meglévő segéddefinícióból.

A .NET esetében az ügynökazonosító a bármely ügynök által meghatározott tulajdonságként jelenik meg string formájában.

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

A funkció jelenleg nem érhető el a Javában.

OpenAIAssistantAgent használata

Az Assistant API minden aspektusához hasonlóan a beszélgetések is távolról vannak tárolva. Minden beszélgetést szálnak nevezünk, és egy egyedi string azonosító azonosítja. A OpenAIAssistantAgent folytatott interakciók ehhez az adott szálazonosítóhoz vannak kötve. Az Assistant API-szál jellemzőit a OpenAIAssistantAgentThread osztály absztraktálja, amely egy AgentThread implementáció.

A OpenAIAssistantAgent jelenleg csak a OpenAIAssistantAgentThreadtípusú szálakat támogatja.

A OpenAIAssistantAgent-t AgentThreadmegadása nélkül is meghívhatja, ha új szálat szeretne elindítani, és a válasz részeként egy új AgentThread-t ad vissza.


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

Meg is hívhatja a OpenAIAssistantAgent-t egy általa létrehozott AgentThread segítségével.

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

Létrehozhat egy OpenAIAssistantAgentThread-t is, amely egy korábbi beszélgetést kezd újra azonosító alapján.

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

A funkció jelenleg nem érhető el a Javában.

OpenAIAssistantAgent törlése

Mivel az asszisztens definíciója távolról van tárolva, az megmarad, ha nem törlődik.
A segéddefiníció törlése közvetlenül az ügyféllel végezhető el.

Megjegyzés: Ha a törlés után megkísérli használni az ügynökpéldányt, az szolgáltatáskivételt eredményez.

A .NET esetében az ügynök azonosítója a string tulajdonságon keresztül jelenik meg, amelyet minden Agent.Id ügynök meghatároz.

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

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

A funkció jelenleg nem érhető el a Javában.

Köztes üzenetek kezelése a(z) OpenAIAssistantAgent használatával

A Szemantikus Kernel OpenAIAssistantAgent egy olyan ügynök meghívására lett kialakítva, amely megfelel a felhasználói lekérdezéseknek vagy kérdéseknek. A meghívás során az ügynök végrehajthat eszközöket a végső válasz lehívásához. A folyamat során létrehozott köztes üzenetek eléréséhez a hívók megadhatnak egy visszahívási függvényt, amely kezeli a FunctionCallContent vagy FunctionResultContent példányokat.

A visszahívási OpenAIAssistantAgent dokumentáció hamarosan elérhető lesz.

A on_intermediate_message vagy agent.invoke(...) visszahívás konfigurálása lehetővé teszi a hívó számára az ügynök végső válaszának kialakítása során generált köztes üzenetek fogadását.

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

Az alábbiak az ügynökhívási folyamatból származó mintakimenetet szemléltetik:

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!

A funkció jelenleg nem érhető el a Javában.

Deklaratív specifikáció

Hamarosan megjelenik a deklaratív specifikációk használatára vonatkozó dokumentáció.

Fontos

Ez a funkció a kísérleti fázisban van. Az ebben a szakaszban található funkciók fejlesztés alatt állnak, és változhatnak, mielőtt továbblépnek az előzetes verzióra vagy a kiadásra jelölt fázisra.

OpenAIAssistantAgent támogatja a példányosítást YAML deklaratív specifikációból. A deklaratív megközelítés lehetővé teszi az ügynök tulajdonságainak, utasításainak, modellkonfigurációjának, eszközeinek és egyéb beállításainak meghatározását egyetlen, naplózható dokumentumban. Így az ügynökök összetétele hordozhatóvá és könnyen kezelhetővé válik a környezetek között.

Megjegyzés:

A deklaratív YAML-ben felsorolt eszközöknek, függvényeknek vagy beépülő moduloknak a építéskor elérhetővé kell lenniük az ügynök számára. A kernelalapú beépülő modulok esetében ez azt jelenti, hogy regisztrálva kell lenniük a Kernelben. Az olyan beépített eszközökhöz, mint a Kódértelmező vagy a Fájlkeresés, a megfelelő konfigurációt és hitelesítő adatokat kell megadni. Az ügynökbetöltő nem hoz létre függvényeket a semmiből. Ha hiányzik egy szükséges összetevő, az ügynök létrehozása sikertelen lesz.

A deklaratív specifikáció használata

Ahelyett, hogy minden lehetséges YAML-konfigurációt számba vesz, ez a szakasz felvázolja a fő alapelveket, és olyan koncepciómintákra mutató hivatkozásokat tartalmaz, amelyek az egyes eszköztípusok teljes kódját mutatják be. Tekintse meg ezeket a koncepció példákat egy OpenAIAssistantAgent végponttól végpontig deklaratív specifikációval rendelkező implementációkhoz.

AzureAssistantAgent Minták:

OpenAIAssistantAgent Minták:

Példa: AzureAIAgent létrehozása a YAML-ből

Egy minimális YAML deklaratív specifikáció az alábbihoz hasonlóan nézhet ki:

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

Az ügynök lekötésére vonatkozó részletekért tekintse meg a fenti kódmintákat.

Kulcsfontosságú pontok

  • A deklaratív specifikációk lehetővé teszik az ügynök szerkezetének, eszközeinek és viselkedésének meghatározását a YAML-ben.
  • Minden hivatkozott eszköznek és beépülő modulnak regisztrálva vagy elérhetőnek kell lennie futásidőben.
  • Az olyan beépített eszközök, mint a Bing, a Fájlkeresés és a Kódértelmező, megfelelő konfigurációt és hitelesítő adatokat igényelnek (gyakran környezeti változókon vagy explicit argumentumokon keresztül).
  • Átfogó példákért tekintse meg a rendelkezésre álló mintahivatkozásokat, amelyek gyakorlati forgatókönyveket mutatnak be, beleértve a beépülő modulregisztrációt, az Azure-identitáskonfigurációt és a speciális eszközhasználatot.

Ez a funkció nem érhető el.

Útmutató

Végponttól végpontig példáért lásd: OpenAIAssistantAgent

Következő lépések

Az OpenAI-válaszügynök felfedezése

  • Last updated on