Skip to content

Commit ae0b45c

Browse files
drewbatgitdrewbatgit
committed
Renaming action-framewok dir to actions
1 parent 094a839 commit ae0b45c

File tree

3 files changed

+300
-0
lines changed

3 files changed

+300
-0
lines changed

‎hub/apps/develop/actions/action-json.md

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
---
2+
title: Action definition JSON schema for Windows Copilot Runtime Action providers
3+
description: Describes the format of the action definition JSON file format for Windows Copilot Runtime Action providers.
4+
ms.topic: article
5+
ms.date: 02/04/2025
6+
ms.localizationpriority: medium
7+
---
8+
9+
10+
11+
# Action definition JSON schema for Windows Copilot Runtime Action providers
12+
13+
This article describes the format of the action definition JSON file format for Windows Copilot Runtime Actions. This file must be included in your project with the **Build Action** set to "Content" and **Copy to Output Directory** set to “Copy if newer”. Specify the package-relative path to the JSON file in your package manifest XML file. For more information, see [Action provider package manifest XML format](action-provider-manifest.md).
14+
15+
## Example action definition JSON file
16+
17+
```json
18+
"version": 1,
19+
"actions": [
20+
{
21+
"id": "Contoso.SampleGreeting",
22+
"description": "Send greeting with Contoso",
23+
"icon": "ms-resource//...",
24+
"inputs": [
25+
{
26+
"name": "UserFriendlyName",
27+
"kind": "Text"
28+
},
29+
{
30+
"name": "PetName",
31+
"kind": "Text",
32+
"required": false
33+
}
34+
],
35+
"inputCombinations": [
36+
{
37+
"inputs": ["UserFriendlyName"],
38+
"description": "Greet ${UserFriendlyName.Text}"
39+
},
40+
{
41+
"inputs": ["UserFriendlyName", "PetName"],
42+
"description": "Greet ${UserFriendlyName.Text} and their pet ${PetName.Text}"
43+
}
44+
],
45+
"contentAgeRating": "child",
46+
"invocation":
47+
{
48+
{
49+
"type": "Uri",
50+
"uri": "contoso://greetUser?userName=${UserFriendlyName.Text}&petName=${PetName.Text}",
51+
},
52+
"where": [
53+
"${UserFriendlyName.Length > 3}"
54+
]
55+
}
56+
},
57+
{
58+
"id": "Contoso.SampleGetText",
59+
"description": "Summarize file with Contoso",
60+
"icon": "ms-resource://...",
61+
"inputs": [
62+
{
63+
"name": "FileToSummarize",
64+
"kind": "File"
65+
}
66+
],
67+
"inputCombinations": [
68+
{
69+
"inputs": ["FileToSummarize"],
70+
"description": "Summarize ${FileToSummarize.Path}"
71+
},
72+
],
73+
"outputs": [
74+
{
75+
"name": "Summary",
76+
"kind": "Text"
77+
}
78+
],
79+
"contentAgeRating": "child",
80+
"invocation": {
81+
"type": "COM",
82+
"clsid": "{...}"
83+
}
84+
}
85+
]
86+
}
87+
```
88+
89+
## Action definition JSON properties
90+
91+
The tables below describe the properties of the action definition JSON file.
92+
93+
### Document root
94+
95+
| Property | Type | Description | Required |
96+
|----------|------|-------------|----------|
97+
| version | string | Schema version. When new functionality added, the version increments by one. | Yes. |
98+
| actions | Action[] | Defines the actions provided by the app. | Yes. |
99+
100+
### Action
101+
102+
| Property | Type | Description | Required |
103+
|----------|------|-------------|----------|
104+
| id | string | Action identifier. Must be unique per app package. This value is not localizable. | Yes |
105+
| description | string | User-facing description for this action. This value is localizable. | Yes |
106+
| icon | string | Localizable icon for the action. This value is an *ms-resource* string for an icon deployed with the app. | No |
107+
| inputs | Inputs[] | List of entities that this action accepts as input. | Yes |
108+
| inputCombinations | InputCombination[] | Provides descriptions for different combinations of inputs. | Yes |
109+
| outputs | Output[] | If specified, must be an empty string in the current release. | No |
110+
| invocation | Invocation | Provides information about how the action is invoked. | Yes |
111+
| contentAgeRating | string | A field name from the [UserAgeConsentGroup](/uwp/api/windows.system.userageconsentgroup)that specifies the appropriate age rating for the action. The allowed values are "Child", "Minor", "Adult". If no value is specified, the default behavior allows access to all ages. | No |
112+
113+
### Output
114+
115+
| Property | Type | Description | Required |
116+
|----------|------|-------------|----------|
117+
| name | string | The variable name of the entity. This value is not localizable. | Yes |
118+
| kind | string | A field name from the **ActionEntityKind** enumeration specifying the entity type. This value is not localizable. The allowed values are "None", "Document", "File", "Photo", "Text". | Yes |
119+
120+
### InputCombination
121+
122+
| Property | Type | Description | Required |
123+
|----------|------|-------------|----------|
124+
| inputs | string[] | A list of Input names for an action invocation. The list may be empty. | Yes |
125+
| description | string | Description for the action invocation. This value is localizable. | No |
126+
| where | string[] | One or more conditional statements determining the conditions under which the action applies. | No |
127+
128+
### Invocation
129+
130+
| Property | Type | Description | Required |
131+
|----------|------|-------------|----------|
132+
| type | string | The instantiation type for the action. The allowed values are "uri" and "com" | Yes |
133+
| uri | string | The absolute URI for launching the action. Entity usage can be included within the string. | Yes, for URI instantiated actions. |
134+
| clsid | string | The class ID for the COM class that implements **IActionProvider**. | Yes, for COM actions |
135+
| inputData | A list of name/value pairs specifying additional data for URI actions. | No. Only valid for URI actions. |
136+
137+
138+
## ActionEntityKind enumeration
139+
140+
The **ActionEntityKind** enumeration specifies the types of entities that are supported by the Windows Copilot Runtime Actions. In the context of a JSON action definition, the entity kinds are string literals that are case-sensitive.
141+
142+
| Entity kind string | Description |
143+
|-------|------------|-------------|
144+
| "File" | Includes all file types that are not supported by photo or document entity types. |
145+
| "Photo" | Image file types. Supported image file extensions are ".jpg", ".jpeg", and ".png" |
146+
| "Document" | Document file types. Supported document file extensions are ".doc", ".docx", ".pdf", ".txt" |
147+
| "Text" | Supports strings of text |
148+
149+
## Entity properties
150+
151+
Each entity type supports one or more properties that provide instance data for the entity. Entity property names are case sensitive.
152+
153+
The following example illustrates how entities are referenced in the query string for actions that are launched via URI activation:
154+
155+
`...?param1=${entityName.property1}&param2=${entityName.property2}`
156+
157+
For information on using entity properties to create conditional sections in the action definition JSON, see [Where clauses](#where-clauses).
158+
159+
### File entity properties
160+
161+
| Property | Type | Description |
162+
|----------|------|-------------|
163+
| "FileName" | string | The name of the file. |
164+
| "Path" | string | The path of the file. |
165+
| "Extension" | string | The extension of the file. |
166+
167+
### Document entity properties
168+
169+
The *Document* entity supports the same properties as *File*.
170+
171+
### Photo entity properties
172+
173+
The *Photo* entity supports all of the properties of *File* in addition to the following properties.
174+
175+
| Property | Type | Description |
176+
|----------|------|-------------|
177+
| "IsTemporaryPath" | boolean | A value specifying whether the photo is stored in a temporary path. For example, this property is true for photos that are stored in memory from a bitmap, not stored permanently in a file. |
178+
179+
### Text entity properties
180+
181+
| Property | Type | Description |
182+
|----------|------|-------------|
183+
| "Text" | string | The full text. |
184+
| "ShortText" | string | A shortened version of the text, suitable for UI display. |
185+
| "Title" | string | The title of the text. |
186+
| "Description" | string | A description of the text. |
187+
| "Length" | double | The length of the text in characters. |
188+
| "WordCount" | double | The number of words in the text. |
189+
190+
## Where clauses
191+
192+
The action definition JSON format supports *where* clauses that can be used to implement conditional logic, such as specifying that an action should be invoked only when an entity property has a specified value.
193+
194+
The following operators can be used with *where* clauses.
195+
196+
| Operator | Description |
197+
|----------|-------------|
198+
| == | Equality |
199+
| ~= | Case-insensitive equality |
200+
| != | Inequality |
201+
| < | Less than |
202+
| <= | Less than or equal to |
203+
| > | Greater than |
204+
| >= | Greater than or equal to |
205+
| \|\| | Logical OR |
206+
| && | Logical AND |
207+
208+
*Where* clauses use the following format:
209+
210+
```json
211+
"where": [
212+
"${<property_accessor>} <operator> <value>"
213+
]
214+
```
215+
216+
The following example shows a *where* clause that evaluates to true if a **File** entity has the file extension ".txt".
217+
218+
```json
219+
"where": [
220+
"${File.Extension} ~= \".txt\""
221+
]
222+
```
223+
224+
Multiple *where* clauses can be combined using the logical AND and logical OR operators.
225+
226+
```json
227+
where": [
228+
"${File.Extension} ~= \".txt\" || ${File.Extension} ~= \".md\""
229+
]
230+
```
231+
232+
## Related articles
233+
234+

‎hub/apps/develop/actions/action-provider-manifest.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: Windows Copilot Runtime Action provider package manifest XML format
3+
description: Describes the package manifest XML format for Windows Copilot Runtime Actions providers.
4+
ms.topic: article
5+
ms.date: 02/05/2024
6+
ms.localizationpriority: medium
7+
---
8+
9+
# Windows Copilot Runtime Action provider package manifest XML format
10+
11+
This article describes the package manifest XML format for Windows Copilot Runtime Actions.
12+
13+
## App extension
14+
15+
The app package manifest file supports many different extensions and features for Windows apps. The app package manifest format is defined by a set of schemas that are documented in the [Package manifest schema reference](/uwp/schemas/appxpackage/uapmanifestschema/schema-root). Action providers declare their registration information within the [uap3:AppExtension](/uwp/schemas/appxpackage/uapmanifestschema/element-uap3-appextension-manual). The **Name** attribute of the extension must be set to "com.microsoft.windows.ai.actions".
16+
17+
Action providers should include the [uap3:Properties](/uwp/schemas/appxpackage/uapmanifestschema/element-uap3-properties-manual) as the child of **uap3:AppExtension**. The package manifest schema does not enforce the structure of the **uap3:Properties** element other than requiring well-formed XML.
18+
19+
Action providers must provide a **Registration** element which specifies the path to the action definition JSON file. For more information, see [Action JSON schema for Windows Copilot Action providers](action-json.md).
20+
21+
```xml
22+
<uap3:Extension Category="windows.appExtension">
23+
<uap3:AppExtension
24+
Name="com.microsoft.windows.ai.actions"
25+
DisplayName="..."
26+
Id="..."
27+
PublicFolder="Assets">
28+
<uap3:Properties>
29+
<Registration>path\to\registration.json</Registration>
30+
</uap3:Properties>
31+
</uap3:AppExtension>
32+
</uap3:Extension>
33+
34+
```
35+
36+
## Additional requirements
37+
38+
Both COM and URI-launched action providers must have package identity. Package identity is declare in the app package manifest file using the [Identity](/uwp/schemas/appxpackage/uapmanifestschema/element-identity) element. For more information, see [An overview of Package Identity in Windows apps](/windows/apps/desktop/modernize/package-identity-overview).
39+
40+
COM-based action providers must have be *full trust apps* which have an integrity level of *mediumIL*. This is declared in the app package manifest file by setting the [*uap10:TrustLevel](/uwp/schemas/appxpackage/uapmanifestschema/element-uap10-extension) attribute to "mediumIL".
41+
42+
URI-launched action providers must also have a trust level of *mediumIL*. If a URI-launched action provider will return outputs, the app must implement the ability to be launched for results. For more information, see [Launch an app for results](/windows/uwp/launch-resume/how-to-launch-an-app-for-results). URI-launched action providers that return outputs must also instantiate the runtime.

‎hub/apps/develop/actions/index.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
title: Windows Copilot Runtime Actions providers
3+
description: Learn about Windows Copilot Runtime Actions providers for Windows apps.
4+
ms.topic: article
5+
ms.date: 02/05/2025
6+
ms.localizationpriority: medium
7+
---
8+
9+
# Windows Copilot Runtime Actions providers
10+
11+
Actions are atomic units of functionality that can be invoked by the Windows Copilot Runtime. Developers can register actions with the system by implementing an action provider app.
12+
13+
14+
## Responsible AI Notes
15+
16+
When building AI backed actions, it is your responsibility as the Action author to perform content moderation and abuse monitoring when it comes to entities returned to the user. For more information about Microsoft Responsible AI policies for more information, see [Microsoft Responsible AI: Principles and approach](https://www.microsoft.com/en-us/ai/principles-and-approach)
17+
18+
> [!NOTE]
19+
> Consider if children should have access to the action using the ‘age-rating’ property in the action definition.
20+
21+
## Related articles
22+
23+
- [Action definition JSON schema for Windows Copilot Runtime Actions providers](action-json.md)
24+
- [Windows Copilot Runtime Actions provider package manifest XML format](action-provider-manifest.md)

0 commit comments

Comments
 (0)