Compartir a través de

Introducción a los iniciadores de agentes en Windows

En este artículo se describen los pasos para crear iniciadores de agentes y los componentes de una aplicación de proveedor del iniciador de agentes. Los iniciadores de agentes en Windows permiten que una aplicación de Windows implemente y registre agentes para que otras aplicaciones y experiencias puedan invocarlos. Para obtener más información, vea Iniciadores de agentes en Información general de Windows.

Implementación de un proveedor de acciones

Los iniciadores de agentes se basan en una implementación especializada de App Actions en una aplicación de proveedor en Windows. Para este tutorial, empiece por implementar un proveedor de acciones siguiendo las instrucciones de Introducción a acciones de aplicación en Windows. En el resto de este artículo se muestran las adiciones y modificaciones que debe realizar en la acción de la app para registrarla y llamarla como lanzador de agentes. Muestra cómo registrar el agente de forma estática (registrada en tiempo de instalación) y dinámicamente para poder agregar y quitar iniciadores de agente por lógica de aplicación.

Modificación del proveedor de acciones para admitir las entidades de entrada necesarias

Para que una acción de aplicación se invoque como iniciador de agentes, debe cumplir los siguientes requisitos para las entidades de entrada:

  • Una entrada debe ser TextActionEntity con el nombre agentName.

  • Una entrada debe ser TextActionEntity con el nombre prompt.

  • Todas las combinaciones de entrada para la acción deben aceptar tanto las entidades agentName como prompt.

  • Invocar la acción de aplicación debe abrir una aplicación en la que el usuario pueda interactuar activamente con el agente, no solo completar el trabajo en segundo plano.

using Microsoft.AI.Actions.Annotations;
using System.Threading.Tasks;
using Windows.AI.Actions;

namespace ZavaAgentProvider
{
    [ActionProvider]
    public sealed class ZavaAgentActionsProvider
    {
        [WindowsAction(
            Id = "ZavaAgentAction",
            Description = "Start an agent for Zava",
            Icon = "ms-resource://Files/Assets/ZavaLogo.png",
            UsesGenerativeAI = true
        )]
        [WindowsActionInputCombination(
            Inputs = ["agentName", "prompt"],
            Description = "Start Zava Agent with '${agentName.Text}'."
        )]
        [WindowsActionInputCombination(
            Inputs = ["agentName", "prompt", "attachedFile"],
            Description = "Start Zava Agent with '${agentName.Text}' and additional context."
        )]

        public async Task StartZavaAgent(
            [Entity(Name = "agentName")] string agentName,
            [Entity(Name = "prompt")] string prompt,
            [Entity(Name = "attachedFile")] FileActionEntity? attachedFile,
            InvocationContext context)
        {
            // Your agent invocation logic here
            await InvokeAgentAsync(agentName, prompt, attachedFile);
        }

        public async Task InvokeAgentAsync(string agentName, string prompt, FileActionEntity? attachedFile)
        {
            // Process the agent invocation with the provided inputs
            if (attachedFile != null)
            {
                await Task.Run(() => $"Starting agent '{agentName}' with prompt '{prompt}' and file context");
            }
            else
            {
                await Task.Run(() => $"Starting agent '{agentName}' with prompt '{prompt}'");
            }
        }
    }
}

En el ejemplo siguiente se muestra el archivo de definición de acción generado a partir de la definición de clase del proveedor de acciones que se muestra en el ejemplo anterior.

{ 
  "version": 3,  
  "actions": [  
    {  
      "id": "ZavaAgentAction",  
      "description": "Start an agent for Zava",  
      "icon": "ms-resource://Files/Assets/ZavaLogo.png",  
      "usesGenerativeAI": true,  
      "allowedAppInvokers": ["*"],  
      "inputs": [  
        {  
          "name": "agentName", "kind": "Text"  
        },  
        {  
          "name": "prompt", "kind": "Text"  
        },  
        {  
          "name": "attachedFile", "kind": "File"  
        }  
      ],  
      "inputCombinations": [  
        // If we don't always expect attachedFile to be present, we can 
        // declare two different inputCombinations  
        {  
          "inputs": [ "agentName", "prompt" ],  
          "description": "Start Zava Agent with '${agentName.Text}'."  
        },  
        {  
          "inputs": [ "agentName", "prompt", "attachedFile" ],  
          "description": "Start Zava Agent with '${agentName.Text}' and additional context."  
        }  
      ],  
      "outputs": [],  
      "invocation": {  
        "type": "Uri",  
        // Example of a valid launch URI using the inputs defined above   
        "uri": "zavaLaunch:invokeAgent?agentName=${agentName.Text}&prompt=${prompt.Text}&context=${attachedFile.Path}"  
      }  
    }  
  ]  
}

Prueba la acción de tu aplicación

Antes de registrar la acción como iniciador de agentes, compruebe que la acción de la aplicación funciona correctamente. Siga la guía de pruebas del artículo Introducción a las acciones de aplicación en Windows para asegurarse de que tu acción:

  1. Se registra correctamente : compruebe que la acción aparece en el catálogo de acciones.
  2. Acepta las entradas necesarias : pruebe que la acción puede recibir las agentName entidades de texto y prompt .
  3. Invoca correctamente : confirme que la lógica de acción se ejecuta cuando se invoca.
  4. Controla las entradas opcionales : si tiene entradas opcionales como attachedFile, pruebe con y sin ellas.

Puede probar la acción de la aplicación mediante las API Windows.AI.Actions o la aplicación App Actions Testing Playground. Una vez que haya confirmado que la acción de la aplicación funciona según lo previsto, puede proceder a registrarla como un lanzador de agentes.

Creación de un archivo JSON de definición de agente

Cree un nuevo archivo JSON en la carpeta del proyecto (o su ubicación preferida) para definir el registro del Assets agente. La definición del agente vincula el agente a la acción de aplicación que creó en el paso anterior.

El valor del campo action_id del manifiesto de definición del agente debe coincidir con el campo id especificado en el manifiesto de definición de acción para una acción incluida en el mismo paquete de aplicación.

{ 
  "manifest_version": "0.1.0", 
  "version": "1.0.0", 
  "name": "Zava.ZavaAgent", 
  "display_name": "ms-resource://zavaAgentDisplayName", 
  "description": "ms-resource://zavaAgentDescription", 
  "icon": "ms-resource://Files/Assets/ZavaLogo.png", 
  "action_id": "ZavaAgentAction"
}

Configura el archivo JSON en Copiar al directorio de salida en las propiedades del proyecto.

  • Para proyectos de C#: haga clic con el botón derecho en el archivo JSON en el Explorador de soluciones, seleccione Propiedades y establezca Copiar en directorio de salida en Copiar si es más reciente o Copiar siempre.
  • Para proyectos de C++: agregue el código siguiente al archivo del proyecto:
<Content Include="Assets\agentRegistration.json">
  <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
</Content>

Registro estático a través del manifiesto del paquete de aplicación

Los iniciadores de agentes pueden registrarse estáticamente (en tiempo de instalación) o dinámicamente (en tiempo de ejecución). En esta sección se trata el registro estático.

El archivo Package.appxmanifest proporciona los detalles del paquete MSIX para una aplicación. Si ha seguido el tutorial de introducción para las acciones de la aplicación, ya ha agregado un elemento uap3:Extension para registrar la acción estableciendo el atributo Name de extensión en com.microsoft.windows.ai.actions. Para registrar la acción como Iniciador de Agente, debe agregar otra extensión de aplicación con el nombre establecido en com.microsoft.windows.ai.appAgent. En el elemento Properties del elemento de extensión de aplicación, debe proporcionar un elemento Registration que especifique la ubicación del archivo JSON de definición del agente.

Nota:

Cada iniciador de agentes registrado estáticamente debe tener su propia entrada AppExtension.

<uap3:Extension Category="windows.appExtension"> 
    <uap3:AppExtension 
      Name="com.microsoft.windows.ai.appAgent" 
      Id="ZavaAgent" 
      DisplayName="Zava Agent" 
      PublicFolder="Assets"> 
        <uap3:Properties> 
          <Registration>agentRegistration.json</Registration> 
        </uap3:Properties> 
    </uap3:AppExtension> 
</uap3:Extension>

Registro dinámico a través del Registro de dispositivos (ODR)

Además del registro estático, puede registrar iniciadores de agentes dinámicamente en tiempo de ejecución mediante el Registro en Dispositivo de Windows (ODR). Este método es útil cuando necesita agregar o quitar agentes en función de la lógica de la aplicación.

Agregar un lanzador de agentes de manera dinámica

Use el odr add-app-agent comando para registrar un iniciador de agentes dinámicamente. Este comando toma la ruta de acceso al archivo JSON de registro del agente.

using System.Diagnostics;

// Create process start info
ProcessStartInfo startInfo = new ProcessStartInfo
{
    FileName = "odr.exe",
    Arguments = $"add-app-agent \"<path to agentDefinition.json>\"",
    UseShellExecute = false,
    RedirectStandardOutput = true,
    RedirectStandardError = true,
    CreateNoWindow = true
};

// Start the ODR process
using Process process = new Process { StartInfo = startInfo };
process.Start();

// Read the output
string output = await process.StandardOutput.ReadToEndAsync();
string error = await process.StandardError.ReadToEndAsync();

await process.WaitForExitAsync();

El comando devuelve una respuesta JSON con la estructura siguiente:

{
  "success": true,
  "agent": {
    "id": "ZavaAgent_cw5n1h2txyewy_Zava.ZavaAgent",
    "version": "1.0.0",
    "name": "Zava.ZavaAgent",
    "display_name": "Zava Agent",
    "description": "Description for Zava agent.",
    "icon": "C://pathToZavaIcon.png",
    "package_family_name": "ZavaPackageFamilyName",
    "action_id": "ZavaAgentAction"
  },
  "message": "Agent registered successfully"
}

Quitar un lanzador de agentes dinámicamente

Use el odr remove-app-agent comando para quitar un iniciador de agentes registrado dinámicamente. Solamente puede quitar agentes que el mismo paquete agrega de manera dinámica.

using System.Diagnostics;

// Create process start info
ProcessStartInfo startInfo = new ProcessStartInfo
{
    FileName = "odr.exe",
    Arguments = $"remove-app-agent \"ZavaAgent_cw5n1h2txyewy_Zava.ZavaAgent\"",
    UseShellExecute = false,
    RedirectStandardOutput = true,
    RedirectStandardError = true,
    CreateNoWindow = true
};

// Start the ODR process
using Process process = new Process { StartInfo = startInfo };
process.Start();

// Read the output
string output = await process.StandardOutput.ReadToEndAsync();
string error = await process.StandardError.ReadToEndAsync();

await process.WaitForExitAsync();

El comando devuelve:

{
  "success": true,
  "message": "Agent removed successfully"
}

Importante

Debido a los requisitos de identidad del paquete, no se puede usar add-app-agent ni remove-app-agent desde una aplicación sin empaquetar. Debe ejecutar estos comandos desde una aplicación empaquetada que también contenga la acción de aplicación asociada.

Enumerar los iniciadores de agentes disponibles

Para detectar todos los iniciadores de agentes registrados en el sistema, use el odr list-app-agents comando . Este comando devuelve todos los iniciadores de agente que puedes invocar.

odr list-app-agents

Este comando devuelve una matriz JSON de definiciones de agente:

{
  "agents": [
    {
      "id": "ZavaAgent_cw5n1h2txyewy_Zava.ZavaAgent",
      "version": "1.0.0",
      "name": "Zava.ZavaAgent",
      "display_name": "Zava Agent",
      "description": "Description for Zava agent.",
      "icon": "C://pathToZavaIcon.png",
      "package_family_name": "ZavaPackageFamilyName",
      "action_id": "ZavaAgentAction"
    }
  ]
}

Use los package_family_name campos y action_id juntos para identificar e invocar la acción de aplicación asociada.

Invoque un lanzador de agentes

Para invocar un iniciador de agentes, siga estos pasos:

  1. Ejecute odr list-app-agents para obtener todos los lanzadores de agentes disponibles.
  2. Seleccione el agente que desea invocar en función de la lógica de la aplicación (por ejemplo, interacción del usuario).
  3. Usar las API Windows.AI.Actions para invocar la acción de aplicación asociada del agente

Este es un ejemplo de invocar un iniciador de agentes mediante las API Windows.AI.Actions:

using Windows.AI.Actions;
using System.Threading.Tasks;

public async Task InvokeAgentLauncherAsync(string packageFamilyName, string actionId, string agentName, string prompt)
{
    // Get the action catalog
    var catalog = ActionCatalog.GetDefault();
    
    // Get all actions for the package
    var actions = await catalog.GetAllActionsAsync();
    
    // Find the specific action by package family name and action ID
    var targetAction = actions.FirstOrDefault(a => 
        a.PackageFamilyName == packageFamilyName && 
        a.Id == actionId);
    
    if (targetAction != null)
    {
        // Create the input entities
        var entityFactory = new ActionEntityFactory();
        var agentNameEntity = entityFactory.CreateTextEntity(agentName);
        var promptEntity = entityFactory.CreateTextEntity(prompt);
        
        // Create input dictionary
        var inputs = new Dictionary<string, ActionEntity>
        {
            { "agentName", agentNameEntity },
            { "prompt", promptEntity }
        };
        
        // Invoke the action
        await targetAction.InvokeAsync(inputs);
    }
}

Pruebe el lanzador del agente

Después de comprobar la funcionalidad de su acción de aplicación, pruebe el registro y la invocación del lanzador de agentes.

Prueba del registro estático

  1. Compile e implemente la aplicación empaquetada con la extensión del agente en el manifiesto.
  2. Abra un terminal y ejecute: 
    odr list-app-agents
  3. Compruebe que el iniciador del agente aparece en la salida con package_family_name y action_id correctos.

Prueba del registro dinámico

  1. Ejecute el odr add-app-agent comando desde la aplicación empaquetada como se muestra en la sección registro dinámico.
  2. Compruebe la salida del comando para confirmar el registro correcto.
  3. Para comprobar el registro, ejecute: 
    odr list-app-agents
  4. Confirme que el agente aparece en la lista.
  5. Pruebe la eliminación ejecutando el comando odr remove-app-agent con el ID de su agente.
  6. Confirme la eliminación ejecutando odr list-app-agents de nuevo y comprobando que el agente ya no aparece.

Invocación del lanzador del agente de prueba

Después de registrar el iniciador del agente, pruebe la invocación integral:

  1. Ejecute odr list-app-agents para obtener los valores package_family_name y action_id de su agente.
  2. Utilice el enfoque de pruebas de acciones de la aplicación del artículo Introducción a las acciones de la aplicación o la herramienta de prueba de acciones para invocar su acción con las entradas necesarias agentName y prompt.
  3. Compruebe que la aplicación recibe las entradas correctamente y que la lógica del agente se ejecuta según lo previsto.
  4. Pruebe entradas opcionales como attachedFile si la acción las admita.
  • Last updated on