Compartilhar via

Usar o Kernel Semântico e o Agent Framework no SDK de Agentes

O SDK do Microsoft 365 Agents concentra-se no suporte à funcionalidade de gerenciamento de conversa, gerenciamento de canal/cliente e autenticação, dentro de um agente. O SDK de Agentes usa o Protocolo de Atividade como o protocolo de comunicação entre o cliente e o código. Ao fornecer gerenciamento de contexto de turno, o código aceita um Activity e dá a oportunidade para o desenvolvedor adicionar lógica de negócios personalizada com base nas informações fornecidas do cliente, encontradas dentro de um Activity. A partir daí, os desenvolvedores podem criar novas atividades a serem enviadas de volta.

O SDK de Agentes permite que os desenvolvedores criem agentes e escolham qualquer modelo de IA, serviços e orquestradores para que possam selecionar o que atende às suas necessidades, dando-lhes flexibilidade para alterar esses componentes quando necessário. Isso inclui o suporte para fluxos de trabalho que envolvem tanto um único agente quanto vários agentes para interações entre eles.

No momento, o Agent Framework dá suporte a C# e Python no status de visualização pública. Os snippets de código neste artigo usam C#. No entanto, a sintaxe é semelhante em outros idiomas com suporte.

Adicionar orquestração e IA

Primeiro, vamos examinar a estrutura de um agente usando o SDK do Microsoft 365 Agents.

Program.cs

Program.cs gerencia o componente de hospedagem do agente, utilizando a infraestrutura de hospedagem de sua escolha, normalmente com base no idioma em que você está criando seu agente. Por exemplo, no C#/.NET, ele usa a infraestrutura de hospedagem ASP.NET para criar um aplicativo. À medida que esse aplicativo está sendo criado, componentes ou serviços são adicionados, como:

  • CloudAdapter: o adaptador de canal principal usado pelo código para interagir com o cliente, aceita solicitações HTTP e cria o TurnContext objeto.
  • IStorage interface: registra o armazenamento que você deseja usar. Muitos exemplos usam Memory Storage, que devem ser substituídos por um armazenamento mais persistente, como Blob ou CosmosDb, para uso em produção. Há suporte para provedores de armazenamento personalizados.
  • AgentApplicationOptions: é usado com AgentApplication e carrega opções da configuração do seu código, como detalhes de hospedagem, registros e extensões (por exemplo, a Extensão do Microsoft Teams)
  • AddAgent<youragent>: Seu código inclui um agente que implementa a classe AgentApplication do SDK que contém sua lógica de negócios principal do agente, por exemplo, EchoBot.cs. Isso carrega o agente.
  • Lógica de roteamento: Adiciona uma rota (api/mensagens) ao host e registra um endpoint

Opções de orquestração

O SDK de Agentes permite que os desenvolvedores usem qualquer SDK de orquestração em seu código, que geralmente interage com o(s) provedor(es) de serviços de IA escolhido(s). Uma opção de orquestração comum é o SDK do Kernel Semântico. Você pode encontrar uma amostra de uso do Kernel Semântico com o SDK de Agentes do Microsoft 365 na amostra de vários turnos do Kernel Semântico.

Orquestrar com Núcleo Semântico

O Kernel Semântico usa o objeto Kernel com o objeto AzureOpenAIChatCompletion a fim de orquestrar solicitações para os pontos de extremidade/implantações configurados do Azure OpenAI ou Foundry. O Kernel objeto faz referência aos serviços de IA que você configurou em Program.cs, gerencia e publica plug-ins e fornece o contexto de execução para uma função ou planejador. Os métodos do Kernel Semântico são executados a partir do Kernel objeto.

Ao registrar seu objeto Kernel no objeto construtor dentro de Program.cs, você pode configurar seu único objeto Kernel para gerenciar essas atividades e evitar reiniciar a instância sempre (com plug-ins etc.). Você pode registrá-lo de algumas maneiras, o mais fácil é usar o método auxiliar interno que cria o objeto kernel e o registra como um singleton:

builder.Services.AddKernel()

No exemplo a seguir, o Kernel é referenciado em sua classe EchoBot.cs e utiliza a injeção de dependência para localizar o registro, de modo a solicitar a reutilização do mesmo objeto que foi criado no momento do registro.

private readonly IKernal _kernel

Esse objeto é populado pelo registro e usado na criação do objeto EchoBot, que utiliza AgentApplicationOptions e kernel no momento da criação. A EchoAgent classe inclui ouvintes de eventos. Por exemplo, OnActivity aguarda ações específicas do cliente e, quando elas ocorrem, aponta para seus métodos personalizados que têm sua lógica de negócios. Essa lógica de negócios pode usar o Kernel objeto que você tem disponível na criação de sua classe.

Orquestrar com Kernel Semântico usando TurnContext e TurnState

O Kernel Semântico fornece o objeto Kernel que funciona como o executor para "orquestrar" com o modelo, registrar e usar plug-ins, além de invocar um planejador. Além disso, ele pode acompanhar o histórico usando ChatHistory e cabe ao desenvolvedor como ele deseja misturar esses objetos para alcançar a experiência do agente e do usuário necessária. Por exemplo, a criação de um registro ChatHistory e a passagem das informações turnState para ele permite que o Kernel esteja ciente das informações do Canal, que são armazenadas em turnState usando o SDK de agentes, para uso no Kernel durante o processo de orquestração.

ChatHistory chatHistory = turnState.Conversation.GetValue("conversation.chatHistory", () => new ChatHistory());

Há vários padrões que você pode usar para integrar e usar o Kernel Semântico com o SDK de Agentes. É uma boa prática abstrair a criação do "agente" do Kernel Semântico em sua própria classe (separada do agente principal, normalmente EchoAgent em exemplos, que gerencia o TurnContext) e, em vez disso, invocar o agente do Kernel Semântico quando necessário, passando o objeto kernel criado toda vez que EchoAgent.cs é criado em cada turno.

O objeto kernel usa um Agent que tem instruções, configurações e plug-ins registrados nele. Esses plug-ins/ferramentas normalmente são de sua própria classe.

Você pode registrar ou importar plugins com o Semantic Kernel do objeto Kernel. A lógica do plug-in normalmente é mantida em sua própria classe com métodos. Essas classes são decoradas com [KernelFunction, Description("Get the current date")] para fornecer mais instruções ao modelo de linguagem sobre como esta ferramenta pode ser utilizada.

this._agent.Kernel.Plugins.Add(KernelPluginFactory.CreateFromType<DateTimePlugin>(serviceProvider: service));

A próxima seção abordará o que foi alterado entre o Kernel Semântico e o Microsoft Agent Framework.

Orquestrar com o Agent Framework

O Microsoft Agent Framework é um kit de desenvolvimento de software livre que sai de uma progressão de vários SDKs na Microsoft. O mais notável é que o Agent Framework combina os orquestradores Semantic Kernel e AutoGen em um único orquestrador que os desenvolvedores podem usar em seu agente para fornecer orquestração para agentes. Mais informações sobre o Agent Framework podem ser encontradas aqui na migração semântica do Kernel do Agent Framework.

Esta seção aborda como o Agent Framework pode ser usado no lugar do Kernel Semântico no SDK do Microsoft 365 Agents. É recomendável examinar a seção Kernel Semântico acima para obter contexto.

Assim como o Kernel Semântico, você pode usar o Agent Framework como o orquestrador para seu agente usando o SDK do Microsoft 365 Agents. Existem algumas diferenças notáveis, sendo a principal a ausência de um objeto Kernel para usar.

O que é usado em vez disso está na classe Program.cs - IChatClient que é criada como um singleton, encapsulada pelo objeto ChatClientAgent e é utilizada com o AzureOpenAIClient para fazer chamadas LLM para provedores com suporte. Essa abordagem pode ser vista como a coisa mais próxima de uma substituição para o objeto Kernel do Semantic Kernel.

builder.Services.AddSingleton<IChatClient>(sp => { return new AzureOpenAIClient(endpointUri, apiKeyCredential).GetChatClient(deployment).AsIChatClient(); });

A EchoBot.cs classe ainda atua como o agente principal que recebe um Activity do cliente usando o SDK de Agentes. Essa classe usa principalmente, a mesma estrutura que com Kernel Semântico, no entanto, em vez de exigir o IKernel objeto de tipo usado pelo Kernel Semântico, a classe agora requer o IChatClient objeto. No exemplo, EchoBot.cs também usa a injeção de dependência para construir o IChatClient, registra-o como Singleton e reutiliza esse objeto cada vez que a classe EchoBot é criada. (Onde iChatClient é encapsulado em ChatClientAgentEchoAgent.cs.)

private readonly ChatClientAgent AFClient;
public EchoBot(AgentApplicationOptions options, IChatClient chatClient) : base(options)
{
 // 
}

Elas abrangem algumas pequenas alterações na criação do agente. Também há atualizações sobre como as ferramentas são registradas (anteriormente conhecidas como plug-ins no Kernel Semântico) e os threads são criados/usados. As mesmas abstrações para classes separadas podem ser aplicadas. Por exemplo, quando você cria o ChatClientAgent, ele inclui opções como temperatura, instruções e registro de ferramenta e é encapsulado por um IChatAgent que foi feito como singleton usando a injeção de dependência. Essa ação pode estar em uma classe separada ou incluída EchoBot.cs como no exemplo.

var toolOptions = new ChatOptions
{
    Temperature = (float?)0.2,
    Tools = new List<AITool>()
};
toolOptions.Tools.Add(AIFunctionFactory.Create(DateTimeFunctionTool.getDate));

AFClient = new ChatClientAgent(chatClient, new ChatClientAgentOptions { Name = "Helper", Instructions = """ Act like a Cat""", ChatOptions = toolOptions });

Em seguida, usando o SDK de Agentes, crie seus ouvintes de eventos em seu EchoBot.cs e desenvolva seus métodos personalizados que incluam sua lógica de negócios, utilizando métodos disponíveis no novo objeto do Agent Framework que você criou do tipo ChatClientAgent para gerenciar o comportamento de orquestração, como RunAsync:

protected async Task OnMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        var userText = turnContext.Activity.Text?.Trim() ?? string.Empty;
        var conversationId = turnContext.Activity.Conversation.Id;
        var thread = _threads.GetOrAdd(conversationId, _ => AFClient.GetNewThread());
        var result = await AFClient.RunAsync(userText, thread, cancellationToken: cancellationToken);

        await turnContext.SendActivityAsync(result.Text, cancellationToken: cancellationToken);
    }

As ferramentas no Agent Framework devem ser sua própria classe e decoradas com descritores. Por exemplo, [Description("Use the tool to be able to return back the date and time right now)")]

Resumo

Este artigo aborda a estrutura de um agente criado usando o SDK do Microsoft 365 Agents. O artigo explica como adicionar o Kernel Semântico como o orquestrador com pontos de extremidade do AI Foundry ou do OpenAI do Azure. Ele também aborda as principais diferenças entre o uso do Kernel Semântico em relação à orquestração do Microsoft Agent Framework.

Próximas etapas

  • Last updated on