Publish a Device with Custom Capabilities

After you build one or more custom capabilities, use the Smart Home AI Toolkit to review and test the complete set of custom and pre-built capabilities included in your device. The toolkit generates an utterance dataset that combines the set of utterances from each capability and runs a batch evaluation. Using AI-guided development, the toolkit helps you build a UI that displays in the Alexa app when the customer controls your device with tap.

Steps to publish a device with custom capabilities

Complete the following steps to test and publish a device with custom capabilities.

1. View the device.
2. Run accuracy tests.
3. Generate the UI for the Alexa app.
4. Publish the device.

Step 1: View the device

You can view the custom and pre-built capabilities that you added to your device during capability definition.

To view the device definition in the Smart Home AI Toolkit

1. Sign in to the Smart Home AI Toolkit.
2. On the Alexa+ Smart Home page, choose Devices, and then select the device to view.
3. To view the capabilities included in your device, open the Overview tab.
4. To view a sample discovery response that includes the custom and pre-built capabilities, open the Discovery Json tab.

Step 2: Run accuracy tests

Use the Smart Home AI Toolkit to generate utterance-to-directive mappings for the collection of capabilities included in your device. Then, run a batch evaluation against the generated utterance dataset. The device-scoped evaluation tests how Alexa handles the utterances across all included capabilities. You can run the capability tests here or in the capability workspace.

Batch evaluation validates that Alexa correctly understands the capability to invoke. Your device must pass batch evaluation before you can publish it for review. If the evaluation fails, the agent gives you actionable feedback pointing to the exact capability, directive, or parameter description to fix.

Generate an utterance dataset

Use the Smart Home AI Toolkit to generate an utterance dataset to test all capabilities included in your device.

To generate test utterances

1. On the menu, choose Test, and then scroll to Full Device Test.
2. Under Generate Test Utterances, to generate a combined set of utterances, choose Generate.
3. If the generation fails, fix any errors in the failed custom capability definition.
   Tip: To fix errors, chat with the agent to add, update, or remove directives, properties, or responses. Then regenerate the capability test utterances and run the batch evaluation.
4. To generate an utterance dataset for the device, under Generate Test Utterances, choose Rerun.
5. After the dataset generation completes, to view the generated utterances, expand Generate Test Utterances. To download the utterances, choose Download dataset.
6. Review the generated utterances. If any mappings don't reflect how customers would naturally speak, instruct the agent to update the utterances or capability, and then choose Rerun.

The downloaded dataset is a JSON file of turns in the following format:

[{
  "dialogId": "d0c0dce2837d494db0a8f69454980972",
  "turns": [{
    "utterance": "feed my dog",
    "actionPlans": [{
      "apiName": "Alexa.Custom.<capabilityName>",
      "parameters": { }
    }]
  }]
}]

Run a batch evaluation

After the dataset generation completes, to run a batch evaluation across all capabilities, under Full Device Test > Batch Evaluation, choose Run Evaluation. If the evaluation fails, update the capability definition, and then regenerate the utterance dataset and run the evaluation for the device.

Test custom utterances

To test errors and edge cases across all capabilities, you can test a set of custom utterances.

To test custom utterances in the Smart Home AI Toolkit

1. Expand Full Device Test > Custom Utterance Testing.
2. Enter one or more customer utterances, one per line.
3. To run the test, choose Run Custom Test.
4. If the test fails, fix any errors in the utterance or capability definition.
5. To rerun the utterances, choose Rerun.

Test in the sandbox

You can run ad-hoc testing in the sandbox at any time to validate the generated utterances and test errors and edge cases. Use the results to modify the generated utterances.

To run end-to-end testing in the sandbox

1. To access the sandbox, choose Sandbox from the menu, or expand the Sandbox panel at the bottom of the page.
2. In the UTTERANCE INPUT field, enter one natural language utterance, and then choose Run.
3. In the RESPONSE panel, validate that Alexa sent the expected directive with the expected properties and property values.

Step 3: Generate the UI

In this step, you build an interactive UI prototype that Alexa displays in the Alexa app and on Alexa-enabled devices with a screen when the customer interacts with your device. The AI-generated UI gives customers a tap interface to control the device. To enable you to preview real device values in the generated UI, the toolkit adds discovery, state report, and directive response views.

To generate the Alexa app UI for your device

1. On the menu, choose UI.
2. To render the UI, choose Generate GUI.
3. Review the generated UI to make sure it reflects the capabilities of your device, including pre-built and custom capabilities.
4. To make changes to the UI, chat with the agent to add, update, remove, or move UI elements.
5. To view the rendered UI on receipt of responses from your add-on, open the following tabs:
   • Discovery response – To edit the discovery response, chat with the agent, or update the response directly in the viewer, and then choose Apply.
   • State Report – To change property values, chat with the agent, or update the context directly in the viewer, and then choose Apply.
   • Directive response – To preview UI changes after the customer asks Alexa to control the device, under Directive, open the drop-down, select the directive, and then choose Confirmation or Error.
6. To review UI changes, open the UI tab.
7. If you change the definition of any custom capabilities associated with the device, or if you add or remove pre-built capabilities, to update the UI, choose Regenerate.

Step 4: Publish the device

To include the custom capabilities in your smart home add-on, you publish the device. Amazon reviews your device and approves your custom capabilities.

A device is ready to publish after it meets the following criteria:

• Every custom capability has a current evaluation that has passed.
• A full device utterance dataset exists and the batch evaluation passed.
• A device UI exists.

To publish a device

1. On the menu, choose Deploy.
2. Review the Deployment readiness checklist. If any items aren't complete, resolve them as follows:
   • If the utterance dataset for a custom capability is not up-to-date, return to Test your custom capability to regenerate the dataset.
   • If the utterance evaluation fails for a custom capability, return to Describe your device capabilities to update the capability definition and rerun the evaluation.
   • If the utterance dataset for the device is not up-to-date or the batch evaluation failed, return to Step 2 to regenerate the utterance dataset and run the evaluation.
3. After the Deployment readiness status is Complete, under Publish device, choose Submit for Publication.

Next steps

After you publish your device with custom capabilities, you can add the interface to the Amazon Web Services (AWS) Lambda function for your add-on. You implement discovery, state handling, and directive processing for your custom interface in the same way you do for pre-built interfaces. For details, continue with Step 2 in Steps to Build Smart Home Add-ons.

Review the following examples of a custom capability in a smart home add-on.

Example discovery response

The following example shows an instance of the custom capability in a discovery response. Use the version of the custom capability that you saved in the Smart Home AI Toolkit.

Discovery response  

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "Unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "Unique ID of the endpoint",
                "manufacturerName": "AnyCompany",
                "description": "Description to be shown in the Alexa app",
                "friendlyName": "AnySmartProduct",
                "displayCategories": ["LIGHTS"],
                "additionalAttributes": {
                    "manufacturer": "AnyCompany",
                    "model": "Model of the device",
                    "serialNumber": "Serial number of the device",
                    "firmwareVersion": "Firmware version of the device",
                    "softwareVersion": "Software version of the device",
                    "customIdentifier": "Optional custom identifier for the device"
                },
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.Custom.AnyCompany.SampleController",
                        "version": "1.0",
                        "properties": {
                            "supported": [{
                                    "name": "exampleProperty"
                                }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.1",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

Example directive request and response

The following example shows a custom capability directive to your add-on. Alexa sends the directive to your add-on in the same way that Alexa sends pre-built directives.

Directive request  

{
    "directive": {
        "header": {
            "namespace": "Alexa.Custom.AnyCompany.SampleController",
            "name": "SetExampleDirective",
            "messageId": "Unique version 4 UUID",
            "correlationToken": "Opaque correlation token",
            "payloadVersion": "1.0"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "an OAuth2 bearer token"
            },
            "endpointId": "Endpoint ID",
            "cookie": {}
        },
        "payload": {
            "exampleProperty": "exampleValue"
        }
    }
}

The following example shows an Alexa response from your add-on that indicates your add-on processed the directive successfully. Include the state of reported properties for your custom capability in the response. If your custom capability defines a custom error response, use that response instead.

Directive response  

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "correlationToken": "Opaque correlation token that matches the request",
            "payloadVersion": "3"
        },
        "endpoint": {
            "endpointId": "Endpoint ID"
        },
        "payload": {}
    },
    "context": {
        "properties": [{
                "namespace": "Alexa.Custom.AnyCompany.SampleController",
                "name": "exampleProperty",
                "value": {
                    "value": "exampleValue"
                },
                "timeOfSample": "2026-07-22T16:21:05.12Z",
                "uncertaintyInMilliseconds": 0
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2026-07-22T16:00:00.00Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}

Example state reporting

The following example shows a state report that includes the reportable properties of the custom capability.

StateReport response  

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "StateReport",
            "messageId": "a unique identifier, preferably a version 4 UUID",
            "correlationToken": "an opaque correlation token that matches the request",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "an OAuth2 bearer token"
            },
            "endpointId": "Endpoint ID"
        },
        "payload": {}
    },
    "context": {
        "properties": [{
                "namespace": "Alexa.Custom.AnyCompany.SampleController",
                "name": "exampleProperty",
                "value": {
                    "value": "exampleValue"
                },
                "timeOfSample": "2026-07-22T16:21:05.12Z",
                "uncertaintyInMilliseconds": 0
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2026-07-22T16:20:58.52Z",
                "uncertaintyInMilliseconds": 500
            }
        ]
    }
}

The following example shows a change report that you proactively send to Alexa when a reportable property of the custom capability changes.

ChangeReport event  

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "ChangeReport",
            "messageId": "a unique identifier, preferably a version 4 UUID",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "an OAuth2 bearer token"
            },
            "endpointId": "Endpoint ID"
        },
        "payload": {
            "change": {
                "cause": {
                    "type": "VOICE_INTERACTION"
                },
                "properties": [{
                    "namespace": "Alexa.Custom.AnyCompany.SampleController",
                    "name": "exampleProperty",
                    "value": {
                        "value": "exampleNewValue"
                    },
                    "timeOfSample": "2026-07-22T16:21:05.12Z",
                    "uncertaintyInMilliseconds": 0
                }]
            }
        }
    },
    "context": {
        "properties": [{
            "namespace": "Alexa.EndpointHealth",
            "name": "connectivity",
            "value": {
                "value": "OK"
            },
            "timeOfSample": "2026-07-22T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
        }]
    }
}

Related topics

• Add Custom Capabilities with the Smart Home AI Toolkit
• Build a Custom Capability
• Implement Smart Home Add-on Code

Last updated: Jul 30, 2026