Windows에서 에이전트 런처 사용 시작하기

이 문서에서는 에이전트 시작 관리자 및 에이전트 시작 관리자 공급자 앱의 구성 요소를 만드는 단계를 설명합니다. Windows의 에이전트 시작 관리자를 사용하면 다른 앱과 환경에서 에이전트를 호출할 수 있도록 Windows 앱에서 에이전트를 구현하고 등록할 수 있습니다. 자세한 내용은 Windows 개요의 에이전트 시작 관리자를 참조하세요.

작업 공급자 구현

에이전트 시작 관리자는 Windows 공급자 앱에서 App Actions의 특수한 구현을 사용합니다. 이 자습서에서는 Windows에서 App Actions 시작의 지침에 따라 작업 공급자를 구현하여 시작합니다. 이 문서의 나머지 부분에는 앱 작업을 등록하고 에이전트 시작 관리자로 호출하는 데 필요한 추가 및 수정 사항이 표시됩니다. 애플리케이션 논리당 에이전트 시작 관리자를 추가하고 제거할 수 있도록 에이전트를 정적으로(설치 시 등록) 동적으로 등록하는 방법을 보여 줍니다.

필요한 입력 엔터티를 지원하도록 작업 공급자 수정

앱 작업을 에이전트 시작 관리자로 호출하려면 입력 엔터티에 대한 다음 요구 사항을 충족해야 합니다.

• 하나의 입력은 이름이 있는 agentName여야 합니다.

• 하나의 입력은 이름이 있는 prompt여야 합니다.

• 작업에 대한 모든 입력 조합은 agentName 및 prompt 엔터티 모두를 수락해야 합니다.

• 앱 작업을 호출하면 백그라운드에서 작업을 완료하는 것이 아니라 사용자가 에이전트와 적극적으로 상호 작용할 수 있는 애플리케이션이 열립니다.

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

다음 예제에서는 이전 예제에 표시된 작업 공급자 클래스 정의에서 생성된 작업 정의 파일을 보여 줍니다.

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

앱 액션 테스트

작업을 에이전트 시작 관리자로 등록하기 전에 앱 작업이 올바르게 작동하는지 확인합니다. Windows에서 App Actions 시작하기 문서의 테스트 지침을 따라 작업을 검증하십시오.

1. 성공적으로 등록 - 작업이 작업 카탈로그에 표시되는지 확인합니다.
2. 필요한 입력을 수락합니다. 작업이 agentName 및 prompt 텍스트 엔터티를 받을 수 있는지 테스트합니다.
3. 올바르게 호출 - 작업 논리가 호출될 때 실행되는지 확인합니다.
4. 선택적 입력을 처리합니다. 같은 attachedFile선택적 입력이 있는 경우 입력을 사용 또는 사용하지 않고 테스트합니다.

Windows.AI.Actions API 또는 앱 작업 테스트 플레이그라운드 앱을 사용하여 앱 작업을 테스트할 수 있습니다. 앱 작업이 예상대로 작동하는지 확인한 후에는 에이전트 시작 관리자로 등록할 수 있습니다.

에이전트 정의 JSON 파일 만들기

프로젝트의 Assets 폴더(또는 원하는 위치)에 새 JSON 파일을 만들어 에이전트 등록을 정의합니다. 에이전트 정의는 이전 단계에서 만든 앱 작업에 에이전트를 연결합니다.

에이전트 정의 매니페스트의 action_id 필드 값은 동일한 앱 패키지에 포함된 작업에 대해 작업 정의 매니페스트에 지정된 ID 필드와 일치해야 합니다.

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

프로젝트 속성에서 출력 디렉터리에 복사하도록 JSON 파일을 설정합니다.

• C# 프로젝트의 경우: 솔루션 탐색기에서 JSON 파일을 마우스 오른쪽 버튼으로 클릭하고 속성을 선택한 후 출력 디렉터리에 복사 옵션을 새로 복사 또는 항상 복사로 설정합니다.
• C++ 프로젝트의 경우: 프로젝트 파일에 다음 코드를 추가합니다.

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

앱 패키지 매니페스트를 통한 정적 등록

에이전트 시작 관리자는 정적으로(설치 시) 또는 동적으로(런타임에) 등록할 수 있습니다. 이 섹션에서는 정적 등록에 대해 설명합니다.

Package.appxmanifest 파일은 앱에 대한 MSIX 패키지의 세부 정보를 제공합니다. 앱 작업에 대한 시작 자습서를 수행한 경우 확장 이름 특성을 .로 설정하여 작업을 등록하는 com.microsoft.windows.ai.actions 요소를 이미 추가했습니다. 에이전트 실행기로 작업을 등록하려면 이름이 로 설정된 다른 앱 확장을 추가해야 합니다. 앱 확장 요소의 Properties 요소 아래에서 에이전트 정의 JSON 파일의 위치를 지정하는 Registration 요소를 제공해야 합니다.

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

ODR(디바이스 레지스트리)을 통한 동적 등록

정적 등록 외에도 Windows On Device Registry(ODR)를 사용하여 런타임에 에이전트 시작 관리자를 동적으로 등록할 수 있습니다. 이 메서드는 애플리케이션 논리에 따라 에이전트를 추가하거나 제거해야 하는 경우에 유용합니다.

에이전트 런처를 동적으로 추가

odr add-app-agent 명령을 사용하여 에이전트 실행기를 동적으로 등록합니다. 이 명령은 에이전트 등록 JSON 파일의 경로를 사용합니다.

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

이 명령은 다음 구조를 사용하여 JSON 응답을 반환합니다.

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

에이전트 런처를 동적으로 제거

odr remove-app-agent 명령을 사용하여 동적으로 등록된 에이전트 런처를 제거합니다. 동일한 패키지가 동적으로 추가하는 에이전트만 제거할 수 있습니다.

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

이 명령은 다음을 반환합니다.

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

사용 가능한 에이전트 런처 나열

시스템에서 등록된 모든 에이전트 시작 관리자를 검색하려면 이 odr list-app-agents 명령을 사용합니다. 이 명령은 호출할 수 있는 모든 에이전트 시작 관리자를 반환합니다.

odr list-app-agents

이 명령은 에이전트 정의의 JSON 배열을 반환합니다.

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

package_family_name 필드와 action_id 필드를 함께 사용하여 연결된 앱 동작을 식별하고 호출합니다.

에이전트 런처 호출

에이전트 시작 관리자를 호출하려면 다음 단계를 수행합니다.

1. 사용 가능한 모든 에이전트 발사기를 가져오기 위해 odr list-app-agents를 호출합니다.
2. 애플리케이션 논리(예: 사용자 상호 작용)에 따라 호출하려는 에이전트를 선택합니다.
3. Windows.AI.Actions API를 사용하여 에이전트의 연결된 앱 동작 호출

Windows.AI.Actions API를 사용하여 에이전트 시작 관리자를 호출하는 예제는 다음과 같습니다.

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

에이전트 실행기 테스트

앱 작업의 기능을 확인한 후 에이전트 시작 관리자 등록 및 호출을 테스트합니다.

정적 등록 테스트

1. 매니페스트에서 에이전트 확장을 사용하여 패키지된 애플리케이션을 빌드하고 배포합니다.
2. 터미널을 열고 다음을 실행합니다.

   odr list-app-agents
   

3. 에이전트 실행기가 출력에 올바른 package_family_name 및 action_id 항목으로 표시되는지 확인합니다.

동적 등록 테스트

1. 동적 등록 섹션에 odr add-app-agent 표시된 대로 패키지된 애플리케이션 내에서 명령을 실행합니다.
2. 명령 출력을 확인하여 성공적인 등록을 확인합니다.
3. 다음을 실행하여 등록을 확인합니다.

   odr list-app-agents
   

4. 에이전트가 목록에 표시되는지 확인합니다.
5. 에이전트의 ID를 사용하여 odr remove-app-agent 명령을 실행하여 제거를 테스트합니다.
6. 다시 실행하고 odr list-app-agents 에이전트가 더 이상 표시되지 않는지 확인하여 제거를 확인합니다.

테스트 에이전트 실행 관리자 호출

에이전트 런처를 등록한 후, 엔드 투 엔드 호출을 테스트합니다.

1. action_id를 실행하여 에이전트의 odr list-app-agents 및 package_family_name 값을 가져옵니다.
2. 앱 작업 시작 문서 또는 작업 테스트 도구의 앱 작업 테스트 방법을 사용하여 필수 agentName 및 prompt 입력으로 작업을 호출합니다.
3. 앱이 입력을 올바르게 수신하고 에이전트 논리가 예상대로 실행되는지 확인합니다.
4. 작업에서 지원하는 경우와 같은 attachedFile 선택적 입력을 테스트합니다.