Introduzione alle utilità di avvio degli agenti in Windows

Questo articolo descrive i passaggi per la creazione di Agent Launchers e i componenti di un'app del provider di Agent Launcher. Gli strumenti di avvio agente in Windows consentono a un'app di Windows di implementare e registrare agenti in modo che altre app ed esperienze possano richiamarle. Per ulteriori informazioni, vedere Panoramica su Agent Launchers in Windows.

Implementare un provider di azioni

Gli avviatori di agenti si basano su un'implementazione specializzata di un'app Azioni app in un'app provider per Windows. Per questa esercitazione, iniziare implementando un provider di azioni seguendo le indicazioni riportate in Introduzione ad Azioni app in Windows. Il resto di questo articolo illustra le aggiunte e le modifiche necessarie per eseguire l'azione dell'app per registrarla e chiamarla come Utilità di avvio agente. Illustra come registrare l'agente sia in modo statico (registrato in fase di installazione) sia in modo dinamico per poter aggiungere e rimuovere Agent Launchers secondo la logica dell'applicazione.

Modificare il fornitore di azioni per supportare le entità di input necessarie

Affinché un'azione dell'app venga richiamata come lanciatore agente, deve soddisfare i requisiti seguenti per le entità di input:

• Un input deve essere TextActionEntity con il nome agentName.

• Un input deve essere TextActionEntity con il nome prompt.

• Tutte le combinazioni di input per l'azione devono accettare sia le agentName entità che prompt .

• Richiamare l'azione dell'app deve aprire un'applicazione in cui l'utente può interagire attivamente con l'agente, non solo completare il lavoro in background.

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

Nell'esempio seguente viene illustrato il file di definizione dell'azione generato dalla definizione della classe del provider di azioni illustrata nell'esempio precedente.

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

Testare l'azione dell'app

Prima di registrare l'azione come Agent Launcher, verificare che l'App Action funzioni correttamente. Seguire le indicazioni per i test nell'articolo Introduzione alle azioni dell'app in Windows per assicurarsi che l'azione sia:

1. Registrazione avvenuta con successo - verificare che l'azione venga visualizzata nel catalogo delle azioni.
2. Accetta gli input necessari : verificare che l'azione possa ricevere le agentName entità di testo e prompt .
3. Richiama correttamente : verificare che la logica di azione venga eseguita quando viene richiamata.
4. Gestisce gli input facoltativi : se sono disponibili input facoltativi, ad esempio attachedFile, eseguire il test sia con che senza di essi.

È possibile testare l'azione dell'app usando le API Windows.AI.Actions o l'app App Actions Testing Playground. Dopo aver confermato che l'Azione dell'App funziona come previsto, è possibile procedere con la registrazione come lanciatore dell'agente.

Creare un file JSON di definizione dell'agente

Creare un nuovo file JSON nella cartella del Assets progetto (o nel percorso preferito) per definire la registrazione dell'agente. La definizione dell'agente collega l'agente all'azione dell'app creata nel passaggio precedente.

Il valore del campo action_id nel manifesto della definizione dell'agente deve corrispondere al campo ID specificato nel manifesto della definizione dell'azione per un'azione inclusa nello stesso pacchetto dell'app.

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

Impostare il file JSON su Copia nella cartella di output nelle proprietà del progetto.

• Per i progetti C#: fare clic con il pulsante destro del mouse sul file JSON in Esplora soluzioni, selezionare Proprietà e impostare Copia nella directory di output su Copia se più recente o Copia sempre.
• Per i progetti C++: aggiungere il codice seguente al file di progetto:

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

Registrazione statica tramite il manifesto del pacchetto applicativo

I launcher degli agenti possono essere registrati in modo statico (in fase di installazione) o in modo dinamico (in fase di esecuzione). Questa sezione illustra la registrazione statica.

Il file Package.appxmanifest fornisce i dettagli del pacchetto MSIX per un'app. Se hai seguito l'esercitazione introduttiva per le azioni dell'app, hai già aggiunto un elemento uap3:Extension per registrare l'azione impostando l'attributo Nome dell'estensione su com.microsoft.windows.ai.actions. Per registrare l'azione come Avvio agente, è necessario aggiungere un'altra estensione dell'app con il Nome impostato su com.microsoft.windows.ai.agentInfo. Nell'elemento Properties dell'elemento dell'estensione dell'app è necessario specificare un elemento Registration che specifica il percorso del file JSON di definizione dell'agente.

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

Registrazione dinamica tramite Registro Dispositivo (ODR)

Oltre alla registrazione statica, è possibile registrare i Launcher Agente in modo dinamico durante l'esecuzione utilizzando il Registro Windows On Device (ODR). Questo metodo è utile quando è necessario aggiungere o rimuovere agenti in base alla logica dell'applicazione.

Aggiungere un launcher agente in modo dinamico

Usare il odr agent-info add comando per registrare dinamicamente un Avviatore di Agenti. Questo comando prende il percorso del file JSON per la registrazione dell'agente.

using System.Diagnostics;

// Create process start info
ProcessStartInfo startInfo = new ProcessStartInfo
{
    FileName = "odr.exe",
    Arguments = $"agent-info add \"<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();

Il comando restituisce una risposta JSON con la struttura seguente:

{
  "agent_id": "ZavaAgent_cw5n1h2txyewy_Zava.ZavaAgent",
  "extended_error": 0
}

Rimuovere un lanciatore di agenti in modo dinamico

Usare il comando odr agent-info remove per rimuovere un launcher agente dinamicamente registrato. È possibile rimuovere solo gli agenti aggiunti dinamicamente dallo stesso pacchetto.

using System.Diagnostics;

// Create process start info
ProcessStartInfo startInfo = new ProcessStartInfo
{
    FileName = "odr.exe",
    Arguments = $"agent-info remove \"<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();

Il comando restituisce:

{
  "extended_error": 0
}

Elenca i lanciatori di agenti disponibili

Per individuare tutti i launcher di agenti registrati nel sistema, utilizzare il comando odr agent-info list. Questo comando restituisce tutti i lanciatori di agenti che puoi invocare.

odr agent-info list

Questo comando restituisce una matrice JSON di definizioni dell'agente:

{
  [
    {
      "package_family_name": "ZavaPackageFamilyName",
      "action_id": "ZavaAgentAction",
      "placeholder_text": "What can you help me with?",
      "version": "1.0.0",
      "id": "ZavaAgent_cw5n1h2txyewy_Zava.ZavaAgent",
      "name": "Zava.ZavaAgent",
      "display_name": "Zava Agent",
      "description": "Description for Zava agent.",
      "icons": [
        {
          "src": "C:\\Users\\[user name]\\AppData\\Local\\ZavaAgent\\Assets\\AgentIcon.png"
        }
      ]
    }
  ]
}

Usare i package_family_name campi e action_id insieme per identificare e richiamare l'azione dell'app associata.

Qualificatori delle icone di fornitura

Quando si eseguono query per gli Avviatori di Agente disponibili tramite odr agent-info list, è possibile fornire uno o più argomenti aggiuntivi per specificare un qualificatore per le risorse dell'icona restituite nell'output del comando. Nella tabella seguente sono elencati i qualificatori di icona che possono essere usati quando si elencano gli Avviatori di Agente.

È possibile specificare più qualificatori in una chiamata a odr agent-info list. È possibile specificare più valori per ogni qualificatore usando una virgola come delimitatore. Se nella query sono presenti qualificatori in formato non valido, il sistema cercherà di restituire i risultati in base ai qualificatori ben formati. Se il sistema non riesce a risolvere le icone, l'elenco delle icone restituite sarà vuoto.

Nell'esempio seguente viene illustrata una chiamata a odr agent-info list, specificando qualificatori per un singolo scale valore e più theme valori.

odr agent-info list --theme dark,light --scale 200

Questo comando restituisce il payload JSON seguente, che include la icons matrice delle icone disponibili che corrispondono ai qualificatori di icona specificati.

{
  [
    {
      "package_family_name": "ZavaPackageFamilyName",
      "action_id": "ZavaAgentAction",
      "placeholder_text": "What can you help me with?",
      "version": "1.0.0",
      "id": "ZavaAgent_cw5n1h2txyewy_Zava.ZavaAgent",
      "name": "Zava.ZavaAgent",
      "display_name": "Zava Agent",
      "description": "Description for Zava agent.",
      "icons": [
        {
          "src": "C:\\Users\\[user name]\\AppData\\Local\\ZavaAgent\\Assets\\AgentIcon.scale-200_theme-dark.png",
          "theme": "dark",
          "scale": "200"
        },
        {
          "src": "C:\\Users\\[user name]\\AppData\\Local\\ZavaAgent\\Assets\\AgentIcon.scale-200_theme-light.png",
          "theme": "light",
          "scale": "200"
        }
      ]
    }
  ]
}

Invocare un launcher agente

Per richiamare un launcher dell'agente, seguire i seguenti passaggi:

1. Chiamare odr agent-info list per ottenere tutti gli strumenti di avvio dell'agente disponibili.
2. Selezionare l'agente che si vuole richiamare in base alla logica dell'applicazione, ad esempio l'interazione dell'utente.
3. Usare le API Windows.AI.Actions per richiamare l'azione app associata dell'agente

Ecco un esempio di invocazione di un Agent Launcher utilizzando le 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);
    }
}

Testare il launcher dell'agente

Dopo aver verificato la funzionalità dell'azione dell'applicazione, testare la registrazione e la chiamata del Launcher dell'agente.

Testare la registrazione statica

1. Crea e distribuisci la tua applicazione impacchettata con l'estensione agente nel file manifest.

2. Aprire un terminale ed eseguire:

   odr agent-info list
   

3. Verificare che l'Agent Launcher sia visualizzato nell'output con il valore corretto package_family_name e action_id.

Testare la registrazione dinamica

1. Eseguire il odr agent-info add comando dall'interno dell'applicazione in pacchetto, come illustrato nella sezione registrazione dinamica.

2. Controllare l'output del comando per confermare la corretta registrazione.

3. Verificare la registrazione eseguendo:

   odr agent-info list
   

4. Verifica che l'agente compaia nell'elenco.

5. Testare la rimozione eseguendo il odr agent-info remove comando con l'ID dell'agente.

6. Confermare la rimozione eseguendo odr agent-info list di nuovo e verificando che l'agente non venga più visualizzato.

Esecuzione del Test Agent Launcher

Dopo aver registrato l'Agent Launcher, testare l'invocazione end-to-end:

1. Eseguire odr agent-info list per ottenere i valori di package_family_name e action_id dell'agente.
2. Usa l'approccio di test delle App Actions descritto nell'articolo Introduzione alle azioni dell'app oppure lo strumento di test per attivare l'azione con gli input richiesti agentName e prompt.
3. Verificare che l'app riceva correttamente gli input e che la logica dell'agente venga eseguita come previsto.
4. Testare gli input facoltativi, ad esempio attachedFile se l'azione li supporta.

Gestire gli errori

Lo stato di esito positivo dei odr agent-info comandi viene restituito nell'output JSON nel extended_error campo . Un valore pari a zero indica l'esito positivo e un valore diverso da zero è un codice di errore esteso che specifica il tipo di errore che si è verificato. Il message campo contiene una stringa leggibile che descrive l'errore. Il message campo è incluso solo nell'output per i comandi con esito negativo.

Di seguito è riportato l'output di esempio di una chiamata a odr agent-info remove dove l'operazione non è riuscita perché l'agente specificato non è stato trovato.

{
  "extended_error": -2147023728,
  "message": "E_NOTFOUND Agent not found: ZavaAgent_cw5n1h2txyewy_Zava.ZavaAgent"
}

I codici di errore che possono essere restituiti dai odr agent-info comandi includono quanto segue.