Merge pull request #1137 from MicrosoftDocs/main

Auto Publish – main to live - 2026-03-16 21:18 UTC

Author: learn-build-service-prod[bot]

docs/agent-launchers/agents-get-started.md

@@ -155,29 +155,28 @@ The value of the **action_id** field in the agent definition manifest must match
 
 Set the JSON file to **Copy to Output Directory** in your project properties:
 
-- **For C# projects**: Right-click the JSON file in Solution Explorer, select **Properties**, and set **Copy to Output Directory** to **Copy if newer** or **Copy always**.
-- **For C++ projects**: Add the following code to your project file:
+* **For C# projects**: Right-click the JSON file in Solution Explorer, select **Properties**, and set **Copy to Output Directory** to **Copy if newer** or **Copy always**.
+* **For C++ projects**: Add the following code to your project file:
 
 ```xml
 <Content Include="Assets\agentRegistration.json">
   <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
 </Content>
 ```
 
-
 ## Static registration via app package manifest
 
 Agent Launchers can register statically (at install time) or dynamically (at runtime). This section covers static registration.
 
-The Package.appxmanifest file provides the details of the MSIX package for an app. If you followed the get started tutorial for app actions, you already added a [uap3:Extension](/uwp/schemas/appxpackage/uapmanifestschema/element-uap3-appextension-manual) element to register the action by setting the extension **Name** attribute to `com.microsoft.windows.ai.actions`. To register the action as an Agent Launcher, you need to add another app extension with the **Name** set to `com.microsoft.windows.ai.appAgent`. Under the **Properties** element of the app extension element, you must provide a **Registration** element that specifies the location of your agent definition JSON file.
+The Package.appxmanifest file provides the details of the MSIX package for an app. If you followed the get started tutorial for app actions, you already added a [uap3:Extension](/uwp/schemas/appxpackage/uapmanifestschema/element-uap3-appextension-manual) element to register the action by setting the extension **Name** attribute to `com.microsoft.windows.ai.actions`. To register the action as an Agent Launcher, you need to add another app extension with the **Name** set to `com.microsoft.windows.ai.agentInfo`. Under the **Properties** element of the app extension element, you must provide a **Registration** element that specifies the location of your agent definition JSON file.
 
 > [!NOTE]
 > Each statically registered Agent Launcher should have its own AppExtension entry.
 
 ```xml
 <uap3:Extension Category="windows.appExtension"> 
     <uap3:AppExtension 
-      Name="com.microsoft.windows.ai.appAgent" 
+      Name="com.microsoft.windows.ai.agentInfo" 
       Id="ZavaAgent" 
       DisplayName="Zava Agent" 
       PublicFolder="Assets"> 
@@ -188,14 +187,13 @@ The Package.appxmanifest file provides the details of the MSIX package for an ap
 </uap3:Extension> 
 ```
 
-
 ## Dynamic registration via On Device Registry (ODR)
 
 In addition to static registration, you can register Agent Launchers dynamically at runtime by using the Windows On Device Registry (ODR). This method is useful when you need to add or remove agents based on application logic.
 
 ### Add an Agent Launcher dynamically
 
-Use the `odr add-app-agent` command to register an Agent Launcher dynamically. This command takes the path to your agent registration JSON file.
+Use the `odr agent-info add` command to register an Agent Launcher dynamically. This command takes the path to your agent registration JSON file.
 
 ```csharp
 using System.Diagnostics;
@@ -204,7 +202,7 @@ using System.Diagnostics;
 ProcessStartInfo startInfo = new ProcessStartInfo
 {
     FileName = "odr.exe",
-    Arguments = $"add-app-agent \"<path to agentDefinition.json>\"",
+    Arguments = $"agent-info add \"<path to agentDefinition.json>\"",
     UseShellExecute = false,
     RedirectStandardOutput = true,
     RedirectStandardError = true,
@@ -226,24 +224,14 @@ The command returns a JSON response with the following structure:
 
 ```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"
+  "agent_id": "ZavaAgent_cw5n1h2txyewy_Zava.ZavaAgent",
+  "extended_error": 0
 }
 ```
 
 ### Remove an Agent Launcher dynamically
 
-Use the `odr remove-app-agent` command to remove a dynamically registered Agent Launcher. You can only remove agents that the same package adds dynamically.
+Use the `odr agent-info remove` command to remove a dynamically registered Agent Launcher. You can only remove agents that the same package adds dynamically.
 
 ```csharp
 using System.Diagnostics;
@@ -252,7 +240,7 @@ using System.Diagnostics;
 ProcessStartInfo startInfo = new ProcessStartInfo
 {
     FileName = "odr.exe",
-    Arguments = $"remove-app-agent \"ZavaAgent_cw5n1h2txyewy_Zava.ZavaAgent\"",
+    Arguments = $"agent-info remove \"<path to agentDefinition.json>\"",
     UseShellExecute = false,
     RedirectStandardOutput = true,
     RedirectStandardError = true,
@@ -274,20 +262,19 @@ The command returns:
 
 ```json
 {
-  "success": true,
-  "message": "Agent removed successfully"
+  "extended_error": 0
 }
 ```
 
 > [!IMPORTANT]
-> Due to package identity requirements, you can't use `add-app-agent` and `remove-app-agent` from an unpackaged app. You must run these commands from within a packaged application that also contains the associated App Action.
+> Due to package identity requirements, you can't use `agent-info add` and `agent-info remove` from an unpackaged app. You must run these commands from within a packaged application that also contains the associated App Action.
 
 ## List available Agent Launchers
 
-To discover all registered Agent Launchers on the system, use the `odr list-app-agents` command. This command returns all Agent Launchers that you can invoke.
+To discover all registered Agent Launchers on the system, use the `odr agent-info list` command. This command returns all Agent Launchers that you can invoke.
 
 ```powershell
-odr list-app-agents
+odr agent-info list
 ```
 
 This command returns a JSON array of agent definitions:
@@ -311,13 +298,63 @@ This command returns a JSON array of agent definitions:
 
 Use the `package_family_name` and `action_id` fields together to identify and invoke the associated App Action.
 
+### Supply icon qualifiers
+
+When querying for available Agent Launchers using `odr agent-info list`, you can supply one or more additional arguments to specify qualifiers for the icon resources that are returned in the command output. The following table lists the icon qualifiers that can be used when listing Agent Launchers.
+
+| Qualifiers | Description |
+|------------|-------------|
+| contrast | Controls high‑contrast mode selection. Valid values: `standard`, `high`, `black`, `white` |
+| language | Specifies the user‑preferred language used to resolve localized resources, for example, "en-US". Only a single value can be specified. |
+| scale  | Indicates the display scale factor used to choose the correctly sized assets, for example, 100, 200, 400 |
+| targetsize | Specifies the pixel side‑length for icons, for example, 16, 24. This is primarily used for file‑type or protocol icons. |
+| theme | Determines app theme influence, for example, `light`, `dark`. The system automatically infers the theme value unless it is overridden by supplying this qualifier. |
+
+You can specify multiple qualifiers in a call to `odr agent-info list`. You can supply multiple values for each qualifier by using a comma as a delimiter. If malformed qualifiers are present in the query, the system will make a best effort to return results based on the well-formed qualifiers. If the system can't resolve any icons, the returned icon list will be empty.
+
+The following example demonstrates a call to `odr agent-info list`, specifying qualifiers for a single `scale` value and multiple `theme` values.
+
+```powershell
+odr agent-info list --theme dark,light --scale 200
+```
+
+This command returns he following JSON payload which includes the `icons` array of the available icons that match the specified icon qualifiers.
+
+```json
+{
+  "agents": [
+    {
+      "id": "ZavaAgent_cw5n1h2txyewy_Zava.ZavaAgent",
+      "version": "1.0.0",
+      "name": "Zava.ZavaAgent",
+      "display_name": "Zava Agent",
+      "description": "Description for Zava agent.",
+      "package_family_name": "ZavaPackageFamilyName",
+      "action_id": "ZavaAgentAction",
+      "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"
+        }
+      ]
+    }
+  ]
+}
+```
+
 ## Invoke an Agent Launcher
 
 To invoke an Agent Launcher, follow these steps:
 
-1. Call `odr list-app-agents` to get all available Agent Launchers.
+1. Call `odr agent-info list` to get all available Agent Launchers.
 1. Select the agent you want to invoke based on your application logic (for example, user interaction).
-3. Use the Windows.AI.Actions APIs to invoke the agent's associated App Action
+1. Use the Windows.AI.Actions APIs to invoke the agent's associated App Action
 
 Here's an example of invoking an Agent Launcher by using the Windows.AI.Actions APIs:
 
@@ -366,28 +403,56 @@ After you verify the functionality of your App Action, test your Agent Launcher
 
 1. Build and deploy your packaged application with the agent extension in the manifest.
 1. Open a terminal and run:
+
    ```powershell
-   odr list-app-agents
+   odr agent-info list
    ```
+
 1. Verify that your Agent Launcher appears in the output with the correct `package_family_name` and `action_id`.
 
 ### Test dynamic registration
 
-1. Run the `odr add-app-agent` command from within your packaged application as shown in the dynamic registration section.
+1. Run the `odr agent-info add` command from within your packaged application as shown in the dynamic registration section.
 1. Check the command output to confirm successful registration.
 1. Verify the registration by running:
+
    ```powershell
-   odr list-app-agents
+   odr agent-info list
    ```
+
 1. Confirm your agent appears in the list.
-1. Test removal by running the `odr remove-app-agent` command with your agent's ID.
-1. Confirm removal by running `odr list-app-agents` again and verifying the agent no longer appears.
+1. Test removal by running the `odr agent-info remove` command with your agent's ID.
+1. Confirm removal by running `odr agent-info list` again and verifying the agent no longer appears.
 
 ### Test Agent Launcher invocation
 
 After you register your Agent Launcher, test the end-to-end invocation:
 
-1. Run `odr list-app-agents` to get your agent's `package_family_name` and `action_id` values.
+1. Run `odr agent-info list` to get your agent's `package_family_name` and `action_id` values.
 1. Use the App Action testing approach from the [Get started with App Actions](../app-actions/actions-get-started.md) article or the Action Test Tool to invoke your action with the required `agentName` and `prompt` inputs.
 1. Verify that your app receives the inputs correctly and your agent logic executes as expected.
 1. Test optional inputs like `attachedFile` if your action supports them.
+
+## Handle errors
+
+The success status of `odr agent-info` commands is returned in the JSON output in the `extended_error` field. A value of zero indicates success and a non-zero value is an extended error code that specifies the type of error that occurred. The `message` field contains a human-readable string describing the error. The `message` field is only included in the output for commands that are unsuccessful.
+
+The following is the example output of a call to `odr agent-info remove` where the operation failed because the specified agent was not found.
+
+```json
+{
+  "extended_error": -2147023728,
+  "message": "E_NOTFOUND Agent not found: ZavaAgent_cw5n1h2txyewy_Zava.ZavaAgent"
+}
+```
+
+Error codes that can be returned from `odr agent-info` commands include the following.
+
+| Error code | Value | Description |
+|------------|-------|-------------|
+|S_OK|0x00000000|Success.|
+| E_FAIL | 0x80004005 | Generic error. |
+| E_INVALIDARG | 0x80070057 | Invalid argument. Examples include invalid JSON path being passed as input for registration or attempting to register an agent that is already registered. |
+| E_ACCESSDENIED | 0x8007000 | Access denied. |
+| E_NOTFOUND | 0x80070490 | Agent being unregistered is not in the registry. |
+| E_ABORT | 0x80004004 | The call was canceled before the operation was completed. |

docs/agent-launchers/agents-json.md

@@ -20,7 +20,8 @@ An Agent Launcher registration links an agent to an App Action that handles the
   "version": "1.0.0", 
   "name": "Zava.ZavaAgent", 
   "display_name": "ms-resource://zavaAgentDisplayName", 
-  "description": "ms-resource://zavaAgentDescription", 
+  "description": "ms-resource://zavaAgentDescription",
+  "placeholder_text": "ms-resource://zavaAgentPlaceHolderText", 
   "icon": "ms-resource://Files/Assets/ZavaLogo.png", 
   "action_id": "ZavaAgentAction"
 } 
@@ -39,6 +40,7 @@ The table below describes the properties of the agent definition JSON file.
 | name | string | A unique identifier for your agent, typically using reverse domain notation (e.g., "Zava.ZavaAgent"). This value is not localizable and must be unique within your package. | Yes |
 | display_name | string | The user-facing display name for the agent. This value is localizable using the `ms-resource://` format to reference a string resource in your app package. | Yes |
 | description | string | A user-facing description of what the agent does. This value is localizable using the `ms-resource://` format to reference a string resource in your app package. | Yes |
+| placeholder_text | string | A user-facing text string for agent providers to offer users a reference query. This value is localizable using the `ms-resource://` format to reference a string resource in your app package. | No |
 | icon | string | The icon for the agent. This value is localizable using the `ms-resource://` format to reference an icon resource deployed with your app package. | Yes |
 | action_id | string | The identifier of the App Action that will handle invocations of this agent. This must match the `id` field of an action defined in the same app package. For information on creating the associated App Action, see [Get started with Agent Launchers on Windows](agents-get-started.md). | Yes |
 
@@ -64,7 +66,7 @@ To localize icon properties, use the following format:
 "icon": "ms-resource://Files/Assets/iconName.png"
 ```
 
-The path is relative to your package root and can reference different icons for different languages through your app's resource system.
+The path is relative to your package root and can reference different icons for different languages through your app's resource system. Agents can provide multiple icons that automatically resolve based on the user’s context, such as  theme (light/dark), high-contrast mode, target size and display scale. For information on naming conventions for icon resources, see [Load images and assets tailored for scale, theme, high contrast, and more](/windows/uwp/app-resources/images-tailored-for-scale-theme-contrast).
 
 ## Relationship to App Actions