Erste Schritte mit Agent-Startprogrammen unter Windows

In diesem Artikel werden die Schritte zum Erstellen von Agent-Startprogrammen und die Komponenten einer Agent Launcher-Anbieter-App beschrieben. Agent-Startprogramme unter Windows ermöglichen es einer Windows-App, Agents zu implementieren und zu registrieren, damit andere Apps und Erfahrungen sie aufrufen können. Weitere Informationen finden Sie unter Agent Launchers unter Windows Overview.

Implementieren eines Aktionsanbieters

Agent-Startprogramme basieren auf einer spezialisierten Implementierung einer App-Aktionen auf der Windows-Anbieter-App. Beginnen Sie in diesem Lernprogramm mit der Implementierung eines Aktionsanbieters, indem Sie die Anleitung in "Erste Schritte mit App-Aktionen unter Windows" ausführen. Der Rest dieses Artikels enthält die Ergänzungen und Änderungen, die Sie an der App-Aktion vornehmen müssen, um sie zu registrieren und als Agent-Startprogramm aufzurufen. Es veranschaulicht, wie der Agent statisch (zur Installationszeit registriert) und dynamisch registriert wird, damit Sie Agent-Startprogramme pro Anwendungslogik hinzufügen und entfernen können.

Ändern des Aktionsanbieters zur Unterstützung der erforderlichen Eingabeentitäten

Damit eine App-Aktion als Agent-Startfeld aufgerufen wird, muss sie die folgenden Anforderungen für Eingabeentitäten erfüllen:

• Eine Eingabe muss ein TextActionEntity-Element mit dem Namen agentNamesein.

• Eine Eingabe muss ein TextActionEntity-Element mit dem Namen promptsein.

• Alle Eingabekombinationen für die Aktion müssen sowohl agentName als auch prompt Entitäten akzeptieren.

• Wenn Sie die App-Aktion aufrufen, sollte eine Anwendung geöffnet werden, in der der Benutzer aktiv mit dem Agent interagieren kann, nicht nur die Arbeit im Hintergrund abschließen.

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

Das folgende Beispiel zeigt die Aktionsdefinitionsdatei, die aus der Klassendefinition des Aktionsanbieters generiert wurde, die im vorherigen Beispiel gezeigt wird.

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

App-Aktion testen

Bevor Sie Ihre Aktion als Agent-Startprogramm registrieren, überprüfen Sie, ob Ihre App-Aktion ordnungsgemäß funktioniert. Befolgen Sie die Testanleitungen im Artikel " Erste Schritte mit App-Aktionen unter Windows ", um ihre Aktion sicherzustellen:

1. Registriert erfolgreich – Überprüfen Sie, ob Ihre Aktion im Aktionskatalog angezeigt wird.
2. Akzeptiert die erforderlichen Eingaben – Testen Sie, dass Ihre Aktion die agentName Entitäten und prompt Textentitäten empfangen kann.
3. Wird ordnungsgemäß aufgerufen – Vergewissern Sie sich, dass die Aktionslogik beim Aufrufen ausgeführt wird.
4. Behandelt optionale Eingaben – Wenn Sie optionale Eingaben wie attachedFile haben, testen Sie sowohl mit als auch ohne diese.

Sie können Ihre App-Aktion testen, indem Sie die Windows.AI.Actions-APIs oder die App "App Actions Testing Playground"-App verwenden. Nachdem Sie bestätigt haben, dass Ihre App-Aktion wie erwartet funktioniert, können Sie sie als Agentenstarter registrieren.

Erstellen einer JSON-Datei für die Agentdefinition

Erstellen Sie eine neue JSON-Datei im Ordner Ihres Projekts Assets (oder Am bevorzugten Speicherort), um die Agent-Registrierung zu definieren. Die Agentdefinition verknüpft Ihren Agent mit der App-Aktion, die Sie im vorherigen Schritt erstellt haben.

Der Wert des Felds action_id im Agentdefinitionsmanifest muss mit dem im Aktionsdefinitionsmanifest angegebenen ID-Feld für eine Aktion übereinstimmen, die im selben App-Paket enthalten ist.

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

Legen Sie die JSON-Datei auf " In Ausgabeverzeichnis kopieren " in den Projekteigenschaften fest:

• Für C#-Projekte: Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf die JSON-Datei, wählen Sie "Eigenschaften" aus, und legen Sie "Kopieren" auf "Ausgabeverzeichnis kopieren" fest, wenn neuer oder "Kopieren" immer.
• Für C++-Projekte: Fügen Sie der Projektdatei den folgenden Code hinzu:

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

Statische Registrierung über App-Paketmanifest

Agent-Startprogramme können statisch (zur Installationszeit) oder dynamisch (zur Laufzeit) registriert werden. In diesem Abschnitt wird die statische Registrierung behandelt.

Die Datei "Package.appxmanifest" enthält die Details des MSIX-Pakets für eine App. Wenn Sie das Lernprogramm "Erste Schritte" für App-Aktionen befolgt haben, haben Sie bereits ein uap3:Extension-Element hinzugefügt, um die Aktion zu registrieren, indem Sie das Erweiterungsname-Attribut auf festlegen com.microsoft.windows.ai.actions. Um die Aktion als Agent-Startprogramm zu registrieren, müssen Sie eine weitere App-Erweiterung hinzufügen, bei der der Name auf com.microsoft.windows.ai.appAgent festgelegt ist. Unter dem Properties-Element des App-Erweiterungselements müssen Sie ein Registration-Element angeben, das den Speicherort Der JSON-Datei der Agentdefinition angibt.

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

Dynamische Registrierung über die On Device Registry (ODR)

Zusätzlich zur statischen Registrierung können Sie Agent-Startprogramme dynamisch zur Laufzeit mithilfe der Windows On Device Registry (ODR) registrieren. Diese Methode ist nützlich, wenn Sie Agents basierend auf der Anwendungslogik hinzufügen oder entfernen müssen.

Agent-Launcher dynamisch hinzufügen

Verwenden Sie den odr add-app-agent Befehl, um ein Agent-Startprogramm dynamisch zu registrieren. Dieser Befehl verwendet den Pfad zu Ihrer JSON-Datei für die Agentregistrierung.

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

Der Befehl gibt eine JSON-Antwort mit der folgenden Struktur zurück:

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

Dynamisches Entfernen eines Agentenstartprogramms

Verwenden Sie den odr remove-app-agent Befehl, um ein dynamisch registriertes Agent-Startprogramm zu entfernen. Sie können nur Agenten entfernen, die das gleiche Paket dynamisch hinzufügt.

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

Der Befehl gibt Folgendes zurück:

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

Verfügbare Agentenstarter auflisten

Verwenden Sie den odr list-app-agents Befehl, um alle registrierten Agent-Startprogramme im System zu ermitteln. Dieser Befehl gibt alle Agent-Startprogramme zurück, die Sie aufrufen können.

odr list-app-agents

Dieser Befehl gibt ein JSON-Array von Agentdefinitionen zurück:

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

Verwenden Sie die Felder package_family_name und action_id zusammen, um die zugeordnete App-Aktion zu identifizieren und aufzurufen.

Aufrufen eines Agenten-Startprogramms

Führen Sie die folgenden Schritte aus, um einen Agentenstarter aufzurufen:

1. Rufen Sie odr list-app-agents auf, um alle verfügbaren Agentenstarter abzurufen.
2. Wählen Sie den Agent aus, den Sie basierend auf Ihrer Anwendungslogik aufrufen möchten (z. B. Benutzerinteraktion).
3. Verwenden der Windows.AI.Actions-APIs zum Aufrufen der zugeordneten App-Aktion des Agents

Hier ist ein Beispiel für das Aufrufen eines Agent-Startfelds mithilfe der Windows.AI.Actions-APIs:

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

Testen des Agent-Launchers

Nachdem Sie die Funktionalität Ihrer App-Aktion überprüft haben, testen Sie die Registrierung und den Aufruf des Agentenstarters.

Testen der statischen Registrierung

1. Erstellen und bereitstellen Sie Ihre verpackte Anwendung mit der Agent-Erweiterung im Manifest.
2. Öffnen Sie ein Terminal, und führen Sie Folgendes aus:

   odr list-app-agents
   

3. Vergewissern Sie sich, dass Ihr Agenten-Launcher in der Ausgabe mit dem richtigen package_family_name und action_id angezeigt wird.

Dynamische Registrierung testen

1. Führen Sie den odr add-app-agent Befehl in Ihrer verpackten Anwendung aus, wie im Abschnitt "dynamische Registrierung" dargestellt.
2. Überprüfen Sie die Befehlsausgabe, um die erfolgreiche Registrierung zu bestätigen.
3. Überprüfen Sie die Registrierung, indem Sie Folgendes ausführen:

   odr list-app-agents
   

4. Bestätigen Sie, dass Ihr Agent in der Liste angezeigt wird.
5. Testen Sie das Entfernen, indem Sie den odr remove-app-agent-Befehl mit der ID Ihres Agents ausführen.
6. Bestätigen Sie das Entfernen, indem Sie es erneut ausführen odr list-app-agents und überprüfen, ob der Agent nicht mehr angezeigt wird.

Aufruf des Test-Agenten-Launchers

Testen Sie nach der Registrierung Ihres Agent-Launchers die End-to-End-Ausführung.

1. Führen Sie odr list-app-agents aus, um die package_family_name- und action_id-Werte Ihres Agents abzurufen.
2. Verwenden Sie den App-Aktionstestansatz aus dem Artikel " Erste Schritte mit App-Aktionen " oder dem Aktionstesttool, um Ihre Aktion mit den erforderlichen agentName und prompt Eingaben aufzurufen.
3. Stellen Sie sicher, dass Ihre App die Eingaben korrekt empfängt und die Agentlogik wie erwartet ausgeführt wird.
4. Testen Sie optionale Eingaben wie attachedFile, wenn Ihre Aktion solche unterstützt.