Comece a usar Lançadores de Agentes no Windows

Este artigo descreve os passos para criar Lançadores de Agentes e os componentes de uma aplicação fornecedora de Lançadores de Agentes. Os Lançadores de Agentes no Windows permitem que uma aplicação Windows implemente e registre agentes para que outras aplicações e experiências possam invocá-los. Para mais informações, consulte Lançadores de Agentes na Visão Geral do Windows.

Implementar um fornecedor de ações

Os Lançadores de Agentes dependem de uma implementação especializada de uma app de Ações de Aplicações num fornecedor da plataforma Windows. Para este tutorial, comece por implementar um provedor de ações seguindo as orientações em Começar com Ações de Aplicação no Windows. O resto deste artigo mostra as adições e modificações que precisa de fazer na ação da aplicação para se registar e chamá-la como Lançador de Agentes. Demonstra como registar o agente tanto de forma estática (registada na instalação) como dinamicamente para que possas adicionar e remover Lançadores de Agentes por lógica de aplicação.

Modificar o provedor de ações para suportar as entidades de entrada necessárias

Para que uma ação de aplicação seja invocada como um Lançador de Agentes, deve cumprir os seguintes requisitos para as entidades de entrada:

• Uma entrada deve ser uma TextActionEntity com o nome agentName.

• Uma entrada deve ser uma TextActionEntity com o nome prompt.

• Todas as combinações de entrada para a ação devem aceitar ambas as agentName entidades e prompt .

• Invocar a Ação da Aplicação deve abrir uma aplicação onde o utilizador possa interagir ativamente com o agente, e não apenas completar o trabalho em 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}'");
            }
        }
    }
}

O exemplo seguinte mostra o ficheiro de definição de ação gerado a partir da definição da classe de provedor de ações mostrada no exemplo 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}"  
      }  
    }  
  ]  
} 

Teste a sua Ação de Aplicação

Antes de registar a sua ação como Lançador de Agentes, verifique se a sua Ação de Aplicação funciona corretamente. Siga as orientações de teste no artigo Comece com Ações de Aplicação no Windows para garantir a sua ação:

1. Regista-se com sucesso - Verifique se a sua ação aparece no catálogo de ações.
2. Aceita as entradas necessárias - Teste se a sua ação pode receber as agentName entidades de texto e prompt.
3. Invoca corretamente - Confirma que a lógica da tua ação é executada quando invocada.
4. Lida com entradas opcionais - Se tiveres entradas opcionais como attachedFile, testa tanto com como sem elas.

Pode testar a sua Ação da Aplicação usando as APIs do Windows.AI.Actions ou a aplicação App Actions Testing Playground. Depois de confirmar que a sua Ação de Aplicação funciona como esperado, pode proceder ao registo como lançador de agentes.

Criar um ficheiro JSON de definição de agente

Crie um novo ficheiro JSON na pasta do Assets seu projeto (ou na sua localização preferida) para definir o registo do seu agente. A definição do agente liga o seu agente à Ação da App que criou na etapa anterior.

O valor do campo action_id no manifesto de definição do agente deve corresponder ao campo id especificado no manifesto de definição de ação para uma ação incluída no mesmo pacote de aplicação.

{ 
  "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"
} 

Defina o ficheiro JSON para Copiar para o Diretório de Saída nas propriedades do seu projeto:

• Para projetos C#: Clique com o botão direito no ficheiro JSON no Explorador de Soluções, selecione Propriedades e defina Copiar para Diretório de Saída para Copiar se for mais recente ou Copiar sempre.
• Para projetos C++: Adicione o seguinte código ao seu ficheiro de projeto:

<Content Include="Assets\agentRegistration.json">
  <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
</Content>

Registo estático via manifesto do pacote de aplicações

Os Lançadores de Agentes podem registar-se estaticamente (no momento da instalação) ou dinamicamente (em tempo de execução). Esta secção cobre o registo estático.

O ficheiro Package.appxmanifest fornece os detalhes do pacote MSIX para uma aplicação. Se seguiste o tutorial para iniciar ações da aplicação, já adicionaste um elemento uap3:Extension para registar a ação definindo o atributo Name da extensão para com.microsoft.windows.ai.actions. Para registar a ação como um Lançador de Agentes, precisa de adicionar outra extensão de aplicação com o Nome definido para com.microsoft.windows.ai.appAgent. No elemento Properties do elemento de extensão da app, deve fornecer um elemento Registration que especifique a localização do ficheiro JSON da definição do seu agente.

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

Registo dinâmico via On Device Registry (ODR)

Para além do registo estático, pode registar os Lançadores de Agentes dinamicamente em tempo de execução usando o Registo de Dispositivos Windows On (ODR). Este método é útil quando é necessário adicionar ou remover agentes com base na lógica da aplicação.

Adicionar um Lançador de Agentes dinamicamente

Use o odr add-app-agent comando para registar dinamicamente um Lançador de Agentes. Este comando utiliza o caminho para o ficheiro JSON de registo do seu 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();

O comando devolve uma resposta JSON com a seguinte estrutura:

{
  "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"
}

Remover dinamicamente um Lançador de Agentes

Use o odr remove-app-agent comando para remover um Lançador de Agentes registado dinamicamente. Só podes remover agentes que o mesmo pacote adiciona dinamicamente.

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

O comando retorna:

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

Lista de lançadores de agentes disponíveis

Para descobrir todos os Lançadores de Agentes registados no sistema, use o odr list-app-agents comando. Este comando devolve todos os Lançadores de Agentes que podes invocar.

odr list-app-agents

Este comando devolve um array JSON de definições de agentes:

{
  "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 os package_family_name campos e action_id em conjunto para identificar e invocar a Ação de Aplicação associada.

Invocar um Lançador de Agentes

Para invocar um Lançador de Agentes, siga estes passos:

1. Ligue odr list-app-agents para aceder a todos os Lançadores de Agentes disponíveis.
2. Selecione o agente que quer invocar com base na lógica da sua aplicação (por exemplo, interação com o utilizador).
3. Utilize as APIs Windows.AI.Actions para invocar a Ação de App associada ao agente

Aqui está um exemplo de invocação de um Lançador de Agentes usando as APIs do 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);
    }
}

Teste o seu Lançador de Agentes

Depois de verificar a funcionalidade da sua Ação de Aplicação, teste o registo e a invocação do seu Lançador de Agentes.

Registo estático de teste

1. Constrói e implementa a tua aplicação empacotada com a extensão do agente no manifesto.
2. Abra um terminal e execute:

   odr list-app-agents
   

3. Verifique se o seu Initiador de Agente aparece na saída com o package_family_name e o action_id corretos.

Registo dinâmico de testes

1. Execute o odr add-app-agent comando dentro da sua aplicação empacotada, conforme mostrado na secção de registo dinâmico.
2. Verifique a saída do comando para confirmar o registo bem-sucedido.
3. Verifique o registo executando:

   odr list-app-agents
   

4. Confirme que o seu agente aparece na lista.
5. Teste a remoção executando o odr remove-app-agent comando com o ID do seu agente.
6. Confirme a remoção correndo odr list-app-agents novamente e verificando que o agente já não aparece.

Invocação do Lançador de Agentes de Teste

Depois de registar o seu Lançador de Agentes, teste a invocação de ponta a ponta:

1. Executa odr list-app-agents para obter os valores package_family_name e action_id do teu agente.
2. Use a abordagem de teste de Ações de Aplicações do artigo Começar com Ações de Aplicações ou a Ferramenta de Teste de Ações para invocar a sua ação com os inputs necessários, agentName e prompt.
3. Verifica se a tua aplicação recebe corretamente as entradas e que a lógica do agente executa como esperado.
4. Testa entradas opcionais, como o attachedFile, se a sua ação as suporta.