Compartir a través de

Uso del kernel semántico y Agent Framework en el SDK de agentes

El SDK de agentes de Microsoft 365 se centra en admitir la administración de conversaciones, la administración de canales o clientes y la funcionalidad de autenticación, dentro de un agente. El SDK de agentes usa el protocolo de actividad como protocolo de comunicación entre el cliente y el código. Al proporcionar la administración del contexto de turno, el código acepta un Activity y ofrece al desarrollador la oportunidad de agregar lógica de negocio personalizada basada en la información proporcionada por el cliente, la cual se encuentra dentro de un Activity. Desde allí, los desarrolladores pueden crear nuevas actividades para ser enviadas de regreso.

El SDK de agentes permite a los desarrolladores crear agentes y elegir cualquier modelo de IA, servicios y orquestadores para que puedan seleccionar lo que satisfaga sus necesidades, a la vez que les ofrece flexibilidad para cambiar esos componentes cuando sea necesario. Esto incluye la compatibilidad con flujos de trabajo de agente único y de varios agentes hacia otros agentes.

Agent Framework admite actualmente C# y Python en estado de versión preliminar pública. Los fragmentos de código de este artículo usan C#. Sin embargo, la sintaxis es similar en otros lenguajes admitidos.

Adición de orquestación e inteligencia artificial

Primero se revisa la estructura de un agente mediante el SDK de agentes de Microsoft 365.

Program.cs

Program.cs administra el componente de hospedaje del agente, utilizando la infraestructura de hospedaje que prefiera, normalmente en función del lenguaje en el que se compila el agente. Por ejemplo, en C#/.NET, usa la infraestructura de hospedaje ASP.NET para compilar una aplicación. A medida que se compila esa aplicación, se agregan componentes o servicios, como:

  • CloudAdapter: adaptador de canal principal que utiliza el código para interactuar con el cliente, acepta solicitudes HTTP y crea el objeto TurnContext.
  • IStorage interfaz: registra el almacenamiento que desea usar. Muchos ejemplos usan Memory Storage que se deben cambiar a almacenamiento más persistente, como Blob o CosmosDb para su uso en producción. Se admiten proveedores de almacenamiento personalizados.
  • AgentApplicationOptions: se usa con AgentApplication y carga opciones de la configuración en el código, como detalles de hospedaje, registro y extensiones (por ejemplo, la extensión de Microsoft Teams)
  • AddAgent<youragent>: su código incluye un agente que implementa la clase AgentApplication desde el SDK que contiene la lógica de negocios principal de agente, por ejemplo, EchoBot.cs. Esto carga el agente.
  • Lógica de enrutamiento: agrega una ruta (api/mensajes) al host y registra un punto de conexión.

Opciones de orquestación

El SDK de agentes permite a los desarrolladores usar cualquier SDK de orquestación en su código, que normalmente interactúa con los proveedores de servicios de IA elegidos. Una opción de orquestación común es el SDK de kernel semántico. Puede encontrar un ejemplo de un kernel semántico usando el SDK de agentes de Microsoft 365 en el ejemplo de varios turnos del kernel semántico.

Orquestrar con "Semantic Kernel"

El kernel semántico usa el Kernel objeto junto con el AzureOpenAIChatCompletion objeto para organizar las solicitudes a los puntos de conexión o implementaciones de Azure OpenAI o Foundry configurados. El Kernel objeto hace referencia a los servicios de inteligencia artificial que configuró en Program.cs, administra y publica complementos y proporciona contexto de ejecución a una función o planificador. Los métodos del kernel semántico se ejecutan desde el Kernel objeto .

Al registrar su Kernel objeto en el objeto generador dentro de Program.cs, puede configurar su único objeto Kernel para administrar estas actividades y evitar reinstanciarlo cada vez (junto con complementos, etc.). Puede registrarlo de varias maneras, lo más sencillo es usar el método auxiliar integrado que crea el objeto kernel y lo registra como singleton:

builder.Services.AddKernel()

En el siguiente ejemplo, se hace referencia a Kernel en la clase EchoBot.cs y se utiliza la inyección de dependencias para buscar el registro, de manera que se solicita reutilizar el mismo objeto creado en el momento del registro.

private readonly IKernal _kernel

Este objeto se rellena a partir de su registro y se emplea en la creación del objeto EchoBot, que toma AgentApplicationOptions y kernel en el momento de la creación. La clase EchoAgent incluye agentes de escucha de eventos. Por ejemplo, OnActivity espera acciones específicas del cliente y, cuando se producen, apunta a los métodos personalizados que tienen la lógica de negocios. Esa lógica de negocios puede usar el Kernel objeto que tiene disponible a partir de la creación de la clase.

Orquestación con kernel semántico mediante TurnContext y TurnState

El kernel semántico proporciona el Kernel objeto que actúa como ejecutor para "orquestar" con el modelo, registrar y usar complementos e invocar un planificador. Además, puede realizar un seguimiento del historial mediante ChatHistory y depende del desarrollador sobre cómo quieren combinar estos objetos para lograr la experiencia del agente y del usuario que necesitan. Por ejemplo, la creación de un registro ChatHistory y el paso de la información turnState a ella, permite al Kernel tener en cuenta la información del Canal, que se almacena en turnState mediante el SDK de agentes para que se pueda usar durante el tiempo de orquestación Kernel.

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

Hay varios patrones que puede usar para integrar y usar kernel semántico con el SDK de agentes. Se considera una buena práctica abstraer la creación del "agente" del kernel semántico en su propia clase (independiente del agente principal, normalmente EchoAgent en los ejemplos, que gestiona el TurnContext), e invocar al agente del kernel semántico cuando sea necesario, pasando el objeto kernel creado desde EchoAgent.cs en cada turno.

El objeto kernel usa un Agent que tiene instrucciones, configuraciones y complementos registrados en él. Estos complementos o herramientas suelen ser su propia clase.

Puede registrar o importar complementos con kernel semántico desde el Kernel objeto . Normalmente, la lógica del complemento se mantiene en su propia clase con métodos. Esas clases están decoradas con [KernelFunction, Description("Get the current date")] para proporcionar más instrucciones al modelo de lenguaje para lo que se puede usar esta herramienta.

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

En la sección siguiente se explica lo que se cambia entre kernel semántico y Microsoft Agent Framework.

Orquestación con Agent Framework

Microsoft Agent Framework es un kit de desarrollo de código abierto que sale de una progresión de varios SDK en Microsoft. En particular, Agent Framework combina los orquestadores Semántico Kernel y AutoGen en un único orquestador que los desarrolladores pueden usar en su agente para proporcionar orquestación para agentes. Puede encontrar más información sobre Agent Framework aquí Migración de Semantic Kernel de Agent Framework.

En esta sección se explica cómo se puede usar Agent Framework en lugar del kernel semántico dentro del SDK de agentes de Microsoft 365. Se recomienda revisar la sección Semantic Kernel anterior para obtener más contexto.

Al igual que el kernel semántico, puede usar Agent Framework como orquestador para el agente mediante el SDK de agentes de Microsoft 365. Hay algunas diferencias notables, la principal es que ya no hay un Kernel objeto disponible para usar.

Lo que se utiliza en su lugar está en la Program.cs clase: el IChatClient, que se crea como un singleton, está encapsulado por el objeto ChatClientAgent y se usa con el AzureOpenAIClient para realizar llamadas LLM a proveedores admitidos. Este enfoque se puede ver como lo más parecido a un sustituto del objeto Kernel del Semantic Kernel.

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

La EchoBot.cs clase sigue funcionando como el agente principal que recibe un Activity del cliente mediante el SDK de Agents. Esta clase usa principalmente, la misma estructura que con kernel semántico, pero en lugar de requerir el IKernel objeto de tipo que usó kernel semántico, la clase ahora requiere el IChatClient objeto . En el ejemplo, EchoBot.cs también usa la inyección de dependencias para construir IChatClient, la registra como Singleton y reutiliza ese objeto cada vez que se crea la clase EchoBot en cada turno. (Donde IChatClient está encapsulado por ChatClientAgent en EchoAgent.cs.)

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

Estos incluyen algunos pequeños cambios en la creación del agente. También hay actualizaciones sobre cómo se registran las herramientas (anteriormente denominadas complementos en Kernel Semántico) y cómo se crean y se utilizan los subprocesos. Se pueden aplicar las mismas abstracciones a clases independientes. Por ejemplo, cuando se crea el ChatClientAgent, incluye opciones como temperatura, instrucciones y registro de herramientas, y está envuelto por un IChatAgent que se fabricó como un singleton utilizando la inserción de dependencias. Esta acción puede estar en una clase independiente o incluirse en EchoBot.cs como en el ejemplo.

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

A continuación, con el SDK de agentes, cree los escuchadores de eventos en EchoBot.cs y cree los métodos personalizados que incluyen la lógica de negocio, mediante métodos disponibles en el nuevo objeto Agent Framework que creó de tipo ChatClientAgent para administrar el comportamiento de orquestación, 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);
    }

Las herramientas de Agent Framework deben ser su propia clase y estar decoradas con descriptores. Por ejemplo: [Description("Use the tool to be able to return back the date and time right now)")]

Resumen

En este artículo se describe la estructura de un agente compilado mediante el SDK de agentes de Microsoft 365. En el artículo se explica cómo agregar el Kernel semántico como orquestador con puntos de conexión de AI Foundry o Azure OpenAI. También trata las principales diferencias entre usar kernel semántico frente a orquestación de Microsoft Agent Framework.

Pasos siguientes

  • Last updated on