この記事では、エージェントランチャーとエージェントランチャープロバイダーアプリのコンポーネントを作成する手順について説明します。 Windows 上のエージェント起動ツールを使用すると、Windows アプリでエージェントを実装して登録し、他のアプリやエクスペリエンスでエージェントを呼び出すことができます。 詳細については、「 Windows 上のエージェント起動ツールの概要」を参照してください。
アクション プロバイダーを実装する
エージェントランチャーは、Windows プロバイダー アプリでのアプリ アクションの特殊な実装に依存します。 このチュートリアルでは、「 Windows でのアプリ アクションの概要」のガイダンスに従って、アクション プロバイダーを実装することから始めます。 この記事の残りの部分では、登録してエージェントランチャーとして呼び出すためにアプリアクションに加える必要がある追加と変更を示します。 アプリケーション ロジックごとにエージェントランチャーを追加および削除できるように、エージェントを静的 (インストール時に登録) と動的の両方で登録する方法を示します。
必要な入力エンティティをサポートするようにアクション プロバイダーを変更する
アプリ アクションをエージェントランチャーとして呼び出すには、入力エンティティに関する次の要件を満たす必要があります。
1 つの入力は、という名前の
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 用アプリ アクションを始めるの記事のテスト ガイダンスに従って、アクションを確認してください。
- 正常に登録 - アクションがアクション カタログに表示されることを確認します。
-
必要な入力を受け入れます 。アクションがテキスト エンティティ
agentNameとpromptを受け取ることができることをテストします。 - 正しく呼び出す - 呼び出 されたときにアクション ロジックが実行されることを確認します。
-
省略可能な入力を処理する -
attachedFileなどの省略可能な入力がある場合は、その入力の有無にかかわらずテストします。
アプリ アクションは、Windows.AI.Actions API または App Actions Testing Playground アプリを使用してテストできます。 アプリ アクションが期待どおりに動作することを確認したら、エージェント起動ツールとして登録に進むことができます。
エージェント定義 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 パッケージの詳細を提供します。 アプリ アクションの概要チュートリアルに従った場合は、拡張機能の Name 属性を に設定して、アクションを登録する com.microsoft.windows.ai.actions 要素を既に追加しました。 アクションをエージェントランチャーとして登録するには、 名前 が com.microsoft.windows.ai.appAgentに設定された別のアプリ拡張機能を追加する必要があります。 アプリ拡張要素の Properties 要素の下に、エージェント定義 JSON ファイルの場所を指定する Registration 要素を指定する必要があります。
注
静的に登録された各エージェントランチャーには、独自の 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>
デバイス レジストリ (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"
}
Important
パッケージ ID の要件により、パッケージ化されていないアプリから add-app-agent と remove-app-agent を使用することはできません。 関連付けられたアプリ アクションも含まれるパッケージ 化されたアプリケーション内からこれらのコマンドを実行する必要があります。
使用可能なエージェントランチャーを一覧表示する
システム上のすべての登録済みエージェント起動ツールを検出するには、 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 フィールドを一緒に使用して、関連付けられているアプリ アクションを識別して呼び出します。
エージェント起動ツールを呼び出す
エージェント起動ツールを呼び出すには、次の手順に従います。
-
odr list-app-agentsを呼び出して、使用可能なすべてのエージェントランチャーを取得します。 - アプリケーション ロジック (ユーザー操作など) に基づいて呼び出すエージェントを選択します。
- 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);
}
}
エージェントランチャーをテストする
アプリ アクションの機能を確認したら、エージェントランチャーの登録と呼び出しをテストします。
静的登録をテストする
- マニフェスト内のエージェント拡張機能を使用して、パッケージ 化されたアプリケーションをビルドしてデプロイします。
- ターミナルを開き、次のコマンドを実行します。
odr list-app-agents - 正しい
package_family_nameとaction_idを使用して、エージェント起動ツールが出力に表示されることを確認します。
動的登録をテストする
- 動的登録セクションに示すように、パッケージ 化されたアプリケーション内から
odr add-app-agentコマンドを実行します。 - 登録が成功したことを確認するには、コマンドの出力を確認します。
- 次を実行して登録を確認します。
odr list-app-agents - エージェントが一覧に表示されたことを確認します。
- エージェントの ID で
odr remove-app-agentコマンドを実行して、削除をテストします。 -
odr list-app-agentsをもう一度実行し、エージェントが表示されなくなったかどうかを確認して、削除を確認します。
エージェント起動プログラムの呼び出しをテストする
エージェントランチャーを登録したら、エンドツーエンドの呼び出しをテストします。
-
odr list-app-agentsを実行して、エージェントのpackage_family_nameとaction_idの値を取得します。 - 必要な
agentNameおよびpromptの入力を使用してアクションを呼び出すには、「App Actions の概要」の記事またはアクション テスト ツールを使用します。 - アプリが入力を正しく受け取り、エージェント ロジックが想定どおりに実行されることを確認します。
- アクションでサポートされている場合は、
attachedFileなどの省略可能な入力をテストします。