Explorando o kernel semântico `OpenAIResponsesAgent`

2025-05-28

Importante

Esse recurso está em estágio experimental. Os recursos nesta fase estão em desenvolvimento e sujeitos a alterações antes de avançar para a versão preliminar ou para o estágio de candidato a lançamento.

O OpenAIResponsesAgent está chegando em breve.

Dica

A documentação detalhada da API relacionada a esta discussão está disponível em:

Recurso atualmente indisponível em Java.

O que é um Agente de Respostas?

A API de Respostas OpenAI é a interface mais avançada do OpenAI para gerar respostas de modelo. Ele dá suporte a entradas de texto e imagem e saídas de texto. Você pode criar interações com estado com o modelo usando a saída de respostas anteriores como entrada. Também é possível estender os recursos do modelo com ferramentas internas para pesquisa de arquivos, pesquisa na Web, uso do computador e muito mais.

Preparando seu ambiente de desenvolvimento

Para continuar desenvolvendo um OpenAIResponsesAgent, configure seu ambiente de desenvolvimento com os pacotes apropriados.

O OpenAIResponsesAgent está chegando em breve.

Instalar o pacote semantic-kernel:

pip install semantic-kernel

Importante

O OpenAIResponsesAgent é suportado nos pacotes do Semantic Kernel em Python 1.27.0 e posteriores.

Recurso atualmente indisponível em Java.

Criando um `OpenAIResponsesAgent`

Para criar um OpenAIResponsesAgent, é necessário primeiro criar um cliente para se comunicar com um serviço remoto.

O OpenAIResponsesAgent está chegando em breve.

Para configurar o modelo usado pela API de Respostas OpenAI ou Azure OpenAI, novas variáveis de ambiente são introduzidas:

OPENAI_RESPONSES_MODEL_ID=""
AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME=""

Defina a variável apropriada dependendo de qual provedor você está usando.

Dica

A versão mínima permitida da API do Azure OpenAI é 2025-03-01-preview. Visite o link a seguir para exibir a disponibilidade da região, o suporte ao modelo e mais detalhes.

Para criar um AzureResponsesAgent para usar com modelos do Azure OpenAI:

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

Como alternativa, para criar um OpenAIResponsesAgent para usar com modelos 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",
)

Recurso atualmente indisponível em Java.

Usando um `OpenAIResponsesAgent`

O OpenAIResponsesAgent está chegando em breve.

A API de Respostas openai dá suporte ao armazenamento remoto opcional de conversas. Por padrão, ao usar um ResponsesAgentThread, as respostas são armazenadas remotamente. Isso permite o uso das API previous_response_id de Respostas para manter o contexto entre invocações.

Cada conversa é tratada como um thread, identificado por uma ID de cadeia de caracteres exclusiva. Todas as interações com o seu OpenAIResponsesAgent estão limitadas a este identificador de fluxo.

A mecânica subjacente do thread da API de Respostas é abstraida pela ResponsesAgentThread classe, que implementa a AgentThread interface.

O OpenAIResponsesAgent atualmente só dá suporte a threads do tipo ResponsesAgentThread.

Você pode invocar o OpenAIResponsesAgent sem especificar um AgentThread, para iniciar uma nova thread, e um novo AgentThread será retornado como parte da resposta.

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

Recurso atualmente indisponível em Java.

Gerenciando mensagens intermediárias com um `OpenAIResponsesAgent`

O Kernel OpenAIResponsesAgent Semântico foi projetado para invocar um agente que atende a consultas ou perguntas do usuário. Durante a invocação, o agente pode executar ferramentas para derivar a resposta final. Para acessar mensagens intermediárias produzidas durante este processo, os chamadores podem fornecer uma função de callback que lida com instâncias de FunctionCallContent ou FunctionResultContent.

O OpenAIResponsesAgent está chegando em breve.

Configurar o on_intermediate_message retorno de chamada dentro de agent.invoke(...) ou agent.invoke_stream(...) permite que o chamador receba mensagens intermediárias geradas durante o processo de formulação da resposta final do 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())

O seguinte demonstra a saída de exemplo do processo de invocação do 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!

Recurso atualmente indisponível em Java.

Especificação declarativa

A documentação sobre como usar especificações declarativas será fornecida em breve.

Importante

O OpenAIResponsesAgent permite a instanciação a partir de uma especificação declarativa YAML. A abordagem declarativa permite definir as propriedades, as instruções, a configuração do modelo, as ferramentas e outras opções do agente em um único documento auditável. Isso torna a composição do agente portátil e facilmente gerenciada entre ambientes.

Observação

Todas as ferramentas, funções ou plug-ins listados no YAML declarativo devem estar disponíveis para o agente no momento da construção. Para plug-ins baseados em kernel, isso significa que eles devem ser registrados no Kernel. Para ferramentas internas, como Interpretador de Código ou Pesquisa de Arquivos, a configuração e as credenciais corretas devem ser fornecidas. O carregador do agente não criará funções do zero. Se um componente necessário estiver ausente, a criação do agente falhará.

Como usar a especificação declarativa

Em vez de enumerar todas as configurações possíveis do YAML, esta seção descreve os principais princípios e fornece links para exemplos de conceito que mostram código completo para cada tipo de ferramenta. Consulte estes exemplos de conceito para implementações de ponta a ponta de um OpenAIResponsesAgent com especificações declarativas:

AzureResponsesAgent Amostras:

OpenAIResponsesAgent Amostras:

Exemplo: criando um AzureAIAgent a partir do YAML

Uma especificação declarativa mínima do YAML pode ser semelhante à seguinte:

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

Para obter detalhes sobre como conectar o agente, consulte os exemplos de código completos acima.

Pontos Principais

As especificações declarativas permitem definir a estrutura, as ferramentas e o comportamento do agente no YAML.
Todas as ferramentas e plug-ins referenciados devem ser registrados ou acessíveis em tempo de execução.
Ferramentas internas como Bing, Pesquisa de Arquivos e Interpretador de Código exigem configuração e credenciais adequadas (geralmente por meio de variáveis de ambiente ou argumentos explícitos).
Para obter exemplos abrangentes, consulte os links de exemplo fornecidos que demonstram cenários práticos, incluindo registro de plug-in, configuração de identidade do Azure e uso avançado de ferramentas.

Esse recurso não está disponível.

Próximas etapas

Explorar Orquestração de Agente

Compartilhar via

Explorando o kernel semântico OpenAIResponsesAgent

O que é um Agente de Respostas?

Preparando seu ambiente de desenvolvimento

Criando um OpenAIResponsesAgent

Usando um OpenAIResponsesAgent

Gerenciando mensagens intermediárias com um OpenAIResponsesAgent

Especificação declarativa

Como usar a especificação declarativa

Exemplo: criando um AzureAIAgent a partir do YAML

Pontos Principais

Próximas etapas

Recursos adicionais

Explorando o kernel semântico `OpenAIResponsesAgent`

Criando um `OpenAIResponsesAgent`

Usando um `OpenAIResponsesAgent`

Gerenciando mensagens intermediárias com um `OpenAIResponsesAgent`