Condividi tramite

Esplorazione del kernel semantico OpenAIResponsesAgent

Importante

Questa funzionalità si trova nella fase sperimentale. Le funzionalità in questa fase sono in fase di sviluppo e soggette a cambiamenti prima di passare alla fase di anteprima o alla versione candidata al rilascio.

Il OpenAIResponsesAgent sarà presto disponibile.

Suggerimento

La documentazione dettagliata dell'API relativa a questa discussione è disponibile all'indirizzo:

Funzionalità attualmente non disponibile in Java.

Che cos'è un agente di risposte?

L'API Risposte OpenAI è l'interfaccia più avanzata di OpenAI per la generazione di risposte del modello. Supporta input di testo e immagine e output di testo. È possibile creare interazioni con stato con il modello, usando l'output delle risposte precedenti come input. È anche possibile estendere le funzionalità del modello con strumenti predefiniti per la ricerca di file, la ricerca Web, l'uso del computer e altro ancora.

Preparazione dell'ambiente di sviluppo

Per procedere con lo sviluppo di un OpenAIResponsesAgent, è necessario configurare l'ambiente di sviluppo con i pacchetti appropriati.

Il OpenAIResponsesAgent sarà presto disponibile.

Installare il pacchetto semantic-kernel:

pip install semantic-kernel

Importante

OpenAIResponsesAgent è supportato nei pacchetti Semantic Kernel Python 1.27.0 e versioni successive.

Funzionalità attualmente non disponibile in Java.

Creazione di un OpenAIResponsesAgent

La creazione di un oggetto OpenAIResponsesAgent richiede prima di tutto la creazione di un client per poter comunicare un servizio remoto.

Il OpenAIResponsesAgent sarà presto disponibile.

Per configurare il modello usato dall'API Risposte OpenAI o OpenAI di Azure, vengono introdotte nuove variabili di ambiente:

OPENAI_RESPONSES_MODEL_ID=""
AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME=""

Impostare la variabile appropriata a seconda del provider in uso.

Suggerimento

La versione minima consentita dell'API OpenAI di Azure è 2025-03-01-preview. Visitare il collegamento seguente per visualizzare la disponibilità dell'area, il supporto del modello e altri dettagli.

Per creare un AzureResponsesAgent oggetto da usare con i modelli OpenAI di Azure:

from semantic_kernel.agents import AzureResponsesAgent
from semantic_kernel.connectors.ai.open_ai import AzureOpenAISettings, OpenAISettings


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

# Create the AzureResponsesAgent instance using the client and the model
agent = AzureResponsesAgent(
    ai_model_id=AzureOpenAISettings().responses_deployment_name,
    client=client,
    instructions="your instructions",
    name="name",
)

In alternativa, per creare un OpenAIResponsesAgent oggetto da usare con i modelli OpenAI:

from semantic_kernel.agents import OpenAIResponsesAgent

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

# Create the OpenAIResponsesAgent instance using the client and the model
agent = OpenAIResponsesAgent(
    ai_model_id=OpenAISettings().responses_model_id,
    client=client,
    instructions="your instructions",
    name="name",
)

Funzionalità attualmente non disponibile in Java.

Utilizzo di un OpenAIResponsesAgent

Il OpenAIResponsesAgent sarà presto disponibile.

L'API Risposte OpenAI supporta l'archiviazione remota facoltativa delle conversazioni. Per impostazione predefinita, quando si usa un ResponsesAgentThread, le risposte vengono archiviate in modalità remota. In questo modo è possibile usare l'API delle Risposte previous_response_id per mantenere il contesto tra le chiamate.

Ogni conversazione viene considerata come un thread, identificata da un ID stringa univoco. Tutte le interazioni con OpenAIResponsesAgent sono limitate a questo identificatore di thread.

I meccanismi sottostanti del thread API Responses vengono astratti dalla ResponsesAgentThread classe , che implementa l'interfaccia AgentThread .

Il OpenAIResponsesAgent supporta attualmente solo i thread di tipo ResponsesAgentThread.

È possibile richiamare il OpenAIResponsesAgent senza specificare un AgentThread, per avviare un nuovo thread e un nuovo AgentThread verrà restituito come parte della risposta.

from semantic_kernel.agents import AzureResponsesAgent

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

# Create the AzureResponsesAgent instance using the client and the model
agent = AzureResponsesAgent(
    ai_model_id=AzureOpenAISettings().responses_deployment_name,
    client=client,
    instructions="your instructions",
    name="name",
)

USER_INPUTS = [
    "My name is John Doe.",
    "Tell me a joke",
    "Explain why this is funny.",
    "What have we been talking about?",
]

thread = None

# Generate the agent response(s)
for user_input in USER_INPUTS:
    print(f"# User: '{user_input}'")
    # Invoke the agent for the current message and print the response
    response = await agent.get_response(messages=user_input, thread=thread)
    print(f"# {response.name}: {response.content}")
    # Update the thread so the previous response id is used
    thread = response.thread

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

Funzionalità attualmente non disponibile in Java.

Gestione dei messaggi intermedi con un OpenAIResponsesAgent

Il kernel OpenAIResponsesAgent semantico è progettato per richiamare un agente che soddisfa le query o le domande degli utenti. Durante la chiamata, l'agente può eseguire strumenti per derivare la risposta finale. Per accedere ai messaggi intermedi generati durante questo processo, i chiamanti possono fornire una funzione di callback che gestisce le istanze di FunctionCallContent o FunctionResultContent.

Il OpenAIResponsesAgent sarà presto disponibile.

La configurazione del on_intermediate_message callback all'interno agent.invoke(...) o agent.invoke_stream(...) consente al chiamante di ricevere messaggi intermedi generati durante il processo di simulazione della risposta finale dell'agente.

import asyncio
from typing import Annotated

from semantic_kernel.agents import AzureResponsesAgent
from semantic_kernel.contents import AuthorRole, FunctionCallContent, FunctionResultContent
from semantic_kernel.contents.chat_message_content import ChatMessageContent
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():
    # 1. Create the client using Azure OpenAI resources and configuration
    client = AzureResponsesAgent.create_client()

    # 2. Create a Semantic Kernel agent for the OpenAI Responses API
    agent = AzureResponsesAgent(
        ai_model_id=AzureOpenAISettings().responses_deployment_name,
        client=client,
        name="Host",
        instructions="Answer questions about the menu.",
        plugins=[MenuPlugin()],
    )

    # 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 = 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,
            ):
                thread = response.thread
                print(f"# {response.name}: {response.content}")
    finally:
        await thread.delete() if thread else None


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

Di seguito viene illustrato l'output di esempio del processo di chiamata dell'agente:

AuthorRole.USER: 'Hello'
Host: Hi there! How can I assist you with the menu 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
Host: The special soup is Clam Chowder. Would you like to know more about any other specials?
AuthorRole.USER: 'What is the special drink?'
Host: The special drink is Chai Tea. Would you like any more information?
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
Host: The Chai Tea is $9.99. Is there anything else you would like to know?
AuthorRole.USER: 'Thank you'
Host: You're welcome! If you have any more questions, feel free to ask. Enjoy your day!

Funzionalità attualmente non disponibile in Java.

Specifica dichiarativa

La documentazione sull'uso delle specifiche dichiarative sarà presto disponibile.

Importante

Questa funzionalità si trova nella fase sperimentale. Le funzionalità in questa fase sono in fase di sviluppo e soggette a cambiamenti prima di passare alla fase di anteprima o alla versione candidata al rilascio.

OpenAIResponsesAgent supporta l'instanziazione da una specifica dichiarativa YAML. L'approccio dichiarativo consente di definire le proprietà, le istruzioni, la configurazione del modello, gli strumenti e altre opzioni in un singolo documento controllabile. Ciò rende la composizione dell'agente portatile e facilmente gestita in ambienti diversi.

Annotazioni

Tutti gli strumenti, le funzioni o i plug-in elencati nel YAML dichiarativo devono essere disponibili per l'agente in fase di costruzione. Per i plug-in basati su kernel, questo significa che devono essere registrati nel kernel. Per gli strumenti predefiniti, ad esempio Interprete codice o Ricerca file, è necessario specificare la configurazione e le credenziali corrette. Il caricatore dell'agente non creerà funzioni da zero. Se manca un componente obbligatorio, la creazione dell'agente avrà esito negativo.

Come usare la specifica dichiarativa

Anziché enumerare ogni possibile configurazione YAML, questa sezione descrive i principi chiave e fornisce collegamenti a esempi di concetti che mostrano codice completo per ogni tipo di strumento. Fare riferimento a questi esempi di concetti per le implementazioni end-to-end di un oggetto OpenAIResponsesAgent con specifiche dichiarative:

AzureResponsesAgent Campioni:

OpenAIResponsesAgent Campioni:

Esempio: Creazione di un'istanza di AzureAIAgent da un file YAML

Una specifica dichiarativa YAML minima potrebbe essere simile alla seguente:

type: openai_responses
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

Per informazioni dettagliate su come collegare l'agente, consultare gli esempi di codice completi precedenti.

Punti chiave

  • Le specifiche dichiarative consentono di definire la struttura dell'agente, gli strumenti e il comportamento in YAML.
  • Tutti gli strumenti e i plug-in a cui si fa riferimento devono essere registrati o accessibili in fase di esecuzione.
  • Gli strumenti predefiniti, ad esempio Bing, Ricerca file e Interprete del codice, richiedono la configurazione e le credenziali appropriate (spesso tramite variabili di ambiente o argomenti espliciti).
  • Per esempi completi, vedere i collegamenti di esempio forniti che illustrano scenari pratici, tra cui la registrazione del plug-in, la configurazione delle identità di Azure e l'uso avanzato degli strumenti.

Questa funzionalità non è disponibile.

Passaggi successivi

Esplora l'orchestrazione degli agenti