Wprowadzenie do uruchamiania agentów w systemie Windows

W tym artykule opisano kroki tworzenia uruchamiaczy agentów i składników aplikacji dostawcy uruchamiaczy agentów. Uruchamianie agentów w systemie Windows umożliwia aplikacji systemu Windows implementowanie i rejestrowanie agentów, aby inne aplikacje i środowiska mogły je wywoływać. Aby uzyskać więcej informacji, zobacz Uruchamianie agentów w systemie Windows — omówienie.

Zaimplementować dostawcę akcji

Programy uruchamiające agentów opierają się na wyspecjalizowanej implementacji akcji aplikacji w aplikacji dostawcy dla systemu Windows. Na potrzeby tego samouczka zacznij od zaimplementowania dostawcy akcji, postępując zgodnie ze wskazówkami w temacie Wprowadzenie do akcji aplikacji w systemie Windows. W pozostałej części tego artykułu przedstawiono dodatki i modyfikacje, które należy wprowadzić w akcję aplikacji, aby zarejestrować ją i wywołać jako Launcher Agenta. Pokazuje on, jak zarejestrować agenta zarówno statycznie (zarejestrowane w czasie instalacji), jak i dynamicznie, aby można było dodawać i usuwać uruchamiacze agentów zgodnie z logiką aplikacji.

Modyfikacja dostawcy działań w celu obsługi wymaganych elementów wejściowych

Aby akcja aplikacji była wywoływana jako uruchamianie agenta, musi spełniać następujące wymagania dotyczące jednostek wejściowych:

Jedno wejście musi być TextActionEntity pod nazwą agentName.
Jedno dane wejściowe musi być wartością TextActionEntity o nazwie prompt.
Wszystkie kombinacje danych wejściowych dla akcji muszą akceptować zarówno jednostki , jak agentName i prompt .
Wywołanie akcji aplikacji powinno spowodować otwarcie aplikacji, w której użytkownik może aktywnie korzystać z agenta, a nie tylko wykonać pracę w tle.

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

Poniższy przykład przedstawia plik definicji akcji wygenerowany na podstawie definicji klasy dostawcy akcji pokazanej w poprzednim przykładzie.

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

Przetestuj działanie swojej aplikacji

Przed zarejestrowaniem swojej akcji jako Agent Launcher sprawdź, czy Akcja aplikacji działa poprawnie. Postępuj zgodnie ze wskazówkami dotyczącymi testowania w artykule Wprowadzenie do akcji aplikacji w systemie Windows, aby mieć pewność, że Twoja akcja:

Rejestruje się pomyślnie — sprawdź, czy akcja jest wyświetlana w wykazie akcji.
Akceptuje wymagane dane wejściowe - Przetestuj, czy Twoja akcja może odbierać agentName i prompt jednostki tekstowe.
Poprawnie wywołuje — upewnij się, że logika akcji jest wykonywana po wywołaniu.
Obsługuje opcjonalne dane wejściowe — jeśli masz opcjonalne dane wejściowe, takie jak attachedFile, przetestuj zarówno z nimi, jak i bez nich.

Akcję aplikacji można przetestować przy użyciu interfejsów API Windows.AI.Actions lub aplikacji App Actions Testing Playground. Po potwierdzeniu, że akcja aplikacji działa zgodnie z oczekiwaniami, możesz zarejestrować ją jako uruchamianie agenta.

Tworzenie pliku JSON definicji agenta

Utwórz nowy plik JSON w folderze projektu Assets (lub preferowanej lokalizacji), aby zdefiniować rejestrację agenta. Definicja agenta łączy agenta z akcją aplikacji utworzoną w poprzednim kroku.

Wartość pola action_id w manifeście definicji agenta musi być zgodna z polem id określonym w manifeście definicji akcji dla akcji zawartej w tym samym pakiecie aplikacji.

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

Ustaw plik JSON na Kopiuj do katalogu wyjściowego we właściwościach projektu:

W przypadku projektów w języku C#: kliknij prawym przyciskiem myszy plik JSON w Eksploratorze rozwiązań, wybierz Właściwości i ustaw opcję Kopiuj do katalogu wyjściowego na Kopiuj, jeśli nowsze lub Zawsze kopiuj.
W przypadku projektów C++: Dodaj następujący kod do pliku projektu:

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

Rejestracja statyczna za pośrednictwem manifestu pakietu aplikacji

Uruchamiacze agentów mogą rejestrować się statycznie (w czasie instalacji) lub dynamicznie (w czasie wykonywania). W tej sekcji opisano rejestrację statyczną.

Plik Package.appxmanifest zawiera szczegóły pakietu MSIX dla aplikacji. Jeśli postępowałeś zgodnie z instrukcjami z samouczka wprowadzenia do akcji aplikacji, już dodałeś element uap3:Extension, aby zarejestrować akcję, ustawiając atrybut Name rozszerzenia na com.microsoft.windows.ai.actions. Aby zarejestrować akcję jako uruchamianie agenta, musisz dodać kolejne rozszerzenie aplikacji z wartością Nazwa ustawioną na com.microsoft.windows.ai.appAgent. W obszarze Właściwości elementu rozszerzenia aplikacji należy podać element Rejestracja , który określa lokalizację pliku JSON definicji agenta.

Uwaga / Notatka

Każdy statycznie zarejestrowany Agent Launcher powinien mieć własny wpis 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>

Rejestracja dynamiczna za pośrednictwem rejestru urządzeń (ODR)

Oprócz rejestracji statycznej, można dynamicznie rejestrować uruchamiacze agenta w trakcie działania programu, korzystając z Rejestru On Device Windows (ODR). Ta metoda jest przydatna w przypadku konieczności dodawania lub usuwania agentów na podstawie logiki aplikacji.

Dynamiczne dodawanie modułu uruchamiania agenta

Użyj polecenia , odr add-app-agent aby dynamicznie zarejestrować moduł uruchamiania agenta. To polecenie pobiera ścieżkę do pliku JSON rejestracji agenta.

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

Polecenie zwraca odpowiedź JSON z następującą strukturą:

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

Dynamiczne usuwanie narzędzia uruchamiania agenta

Użyj polecenia , odr remove-app-agent aby usunąć dynamicznie zarejestrowany moduł uruchamiania agenta. Można usuwać tylko agentów, których ten sam pakiet dodaje dynamicznie.

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

Polecenie zwraca następujące polecenie:

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

Ważne

Ze względu na wymagania dotyczące tożsamości pakietu nie można używać add-app-agent i remove-app-agent z niezapakowanej aplikacji. Należy uruchomić te polecenia z poziomu spakowanej aplikacji, która zawiera również skojarzoną akcję aplikacji.

Wyświetlanie listy dostępnych modułów uruchamiania agentów

Aby odnaleźć wszystkie zarejestrowane programy startowe agentów w systemie, użyj polecenia odr list-app-agents. To polecenie zwraca wszystkie moduły uruchamiające agentów, które można wywołać.

odr list-app-agents

To polecenie zwraca tablicę JSON definicji agenta:

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

Użyj pól package_family_name i action_id razem, aby zidentyfikować i wywołać skojarzoną akcję aplikacji.

Uruchomienie programu uruchamiającego agenta

Aby wywołać Agent Launchera, wykonaj następujące kroki:

Wywołaj odr list-app-agents, aby pobrać wszystkie dostępne programy uruchamiające agentów.
Wybierz agenta, który chcesz wywołać na podstawie logiki aplikacji (na przykład interakcji z użytkownikiem).
Użyj interfejsów API Windows.AI.Actions, aby wywołać powiązaną akcję aplikacji agenta.

Oto przykład wywoływania modułu uruchamiania agenta przy użyciu interfejsów 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);
    }
}

Testuj program uruchamiający agenta

Po zweryfikowaniu funkcjonalności działania aplikacji przetestuj rejestrację i wywołanie uruchamiacza agenta.

Testowanie rejestracji statycznej

Skompiluj i wdróż spakowana aplikację przy użyciu rozszerzenia agenta w manifeście.
Otwórz terminal i uruchom:
```
odr list-app-agents
```
Sprawdź, czy Agent Launcher jest wyświetlany w danych wyjściowych z poprawnymi znacznikami package_family_name i action_id.

Testowanie rejestracji dynamicznej

odr add-app-agent Uruchom polecenie z poziomu spakowanej aplikacji, jak pokazano w sekcji rejestracji dynamicznej.
Sprawdź dane wyjściowe polecenia, aby potwierdzić pomyślną rejestrację.
Sprawdź rejestrację, uruchamiając polecenie:
```
odr list-app-agents
```
Upewnij się, że agent pojawi się na liście.
Przetestuj usunięcie, uruchamiając polecenie odr remove-app-agent z identyfikatorem agenta.
Potwierdź usunięcie, ponownie uruchamiając polecenie odr list-app-agents i sprawdzając, czy agent nie jest już widoczny.

Wywołanie uruchamiania agenta testowego

Po zarejestrowaniu modułu uruchamiania agenta przetestuj kompleksowe wywołanie:

Uruchom odr list-app-agents, aby pobrać wartości package_family_name i action_id agenta.
Użyj podejścia do testowania akcji aplikacji z artykułu Wprowadzenie do akcji aplikacji lub Narzędzia do testowania akcji, aby wywołać akcję z wymaganymi agentName oraz prompt danymi wejściowymi.
Sprawdź, czy aplikacja prawidłowo odbiera dane wejściowe, a logika agenta jest wykonywana zgodnie z oczekiwaniami.
Przetestuj opcjonalne dane wejściowe, takie jak attachedFile jeśli akcja je obsługuje.

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-12-12