Explorando o Kernel Semântico `OpenAIResponsesAgent`

2025-05-28

Importante

Esta característica encontra-se em fase experimental. Os recursos nesta fase estão em desenvolvimento e sujeitos a alterações antes de avançar para a versão de pré-visualização ou versão candidata.

O OpenAIResponsesAgent está chegando em breve.

Sugestão

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 OpenAI Responses API é a interface mais avançada da OpenAI para gerar respostas de modelo. Ele suporta entradas de texto e imagem, e saídas de texto. É possível criar interações com estado com o modelo, utilizando os resultados de respostas anteriores como entrada. Também é possível estender os recursos do modelo com ferramentas integradas para pesquisa de arquivos, pesquisa na web, uso do computador e muito mais.

Preparando seu ambiente de desenvolvimento

Para prosseguir com o desenvolvimento de um OpenAIResponsesAgent, configure seu ambiente de desenvolvimento com os pacotes apropriados.

O OpenAIResponsesAgent está chegando em breve.

Instale o pacote semantic-kernel:

pip install semantic-kernel

Importante

O OpenAIResponsesAgent é suportado nos pacotes Python do Kernel Semântico 1.27.0 e posteriores.

Recurso atualmente indisponível em Java.

Criando uma `OpenAIResponsesAgent`

Criar um OpenAIResponsesAgent requer primeiro a criação de um cliente para poder interagir com um serviço remoto.

O OpenAIResponsesAgent está chegando em breve.

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

OPENAI_RESPONSES_MODEL_ID=""
AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME=""

Defina a variável apropriada dependendo do provedor que você está usando.

Sugestão

A versão mínima permitida da API do Azure OpenAI é 2025-03-01-preview. Visite o link a seguir para ver 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 OpenAI Responses suporta armazenamento remoto opcional de conversas. Por padrão, ao usar um ResponsesAgentThread, as respostas são armazenadas remotamente. Isso permite o uso das APIs previous_response_id de respostas para manter o contexto entre invocações.

Cada conversa é tratada como um thread, identificado por um ID de cadeia de caracteres exclusivo. Todas as interações com o seu OpenAIResponsesAgent têm como escopo esse identificador de thread.

A mecânica subjacente da thread da API Responses é abstraída pela ResponsesAgentThread classe, que implementa a interface AgentThread.

Atualmente, o OpenAIResponsesAgent suporta apenas tópicos do tipo ResponsesAgentThread.

Você pode invocar o OpenAIResponsesAgent sem especificar um AgentThread, para iniciar um novo 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.

Gerir mensagens intermediárias com um `OpenAIResponsesAgent`

O Kernel Semântico OpenAIResponsesAgent foi projetado para invocar um agente que atenda às 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 esse processo, os chamadores podem fornecer uma função de retorno de chamada que lida com instâncias de FunctionCallContent ou FunctionResultContent.

O OpenAIResponsesAgent está chegando em breve.

Configurar o on_intermediate_message callback dentro de agent.invoke(...) ou agent.invoke_stream(...) permite ao chamador receber 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())

A seguir 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 o uso de especificações declarativas será disponibilizada em breve.

Importante

O OpenAIResponsesAgent suporta instanciação de uma especificação declarativa YAML. A abordagem declarativa permite definir as propriedades, instruções, configuração do modelo, 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 em todos os ambientes.

Observação

Quaisquer ferramentas, funções ou plugins listados no YAML declarativo devem estar disponíveis para o agente no momento da construção. Para plugins 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 faltando, 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 princípios-chave e fornece links para exemplos de conceito que mostram o 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 YAML mínima pode ter a seguinte aparência:

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 plugins 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.

Este recurso não está disponível.

Próximas Etapas

Explore a orquestração de agentes

Partilhar via

Explorando o Kernel Semântico OpenAIResponsesAgent

O que é um Agente de Respostas?

Preparando seu ambiente de desenvolvimento

Criando uma OpenAIResponsesAgent

Usando um OpenAIResponsesAgent

Gerir 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 uma `OpenAIResponsesAgent`

Usando um `OpenAIResponsesAgent`

Gerir mensagens intermediárias com um `OpenAIResponsesAgent`