App Skills: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

Track a package with an app skill

A shipping app has declared a getPackageTracking tool in its App Tools extension and a package-tracking skill in its App Skills extension. An agent working on the site uses the skill to answer "Where is order 1Z999AA10123456784?".

To track a package with an app skill:

1. Call List App Skills with the site in context. The response lists every activated skill of every installed app, without guidelines.

2. Match the user's request against each skill's description, tags and examples, and take the id of the skill that fits. Here, package-tracking matches on the tracking-number example.

3. Call Get App Skill with that id. The response is the same skill with its guidelines. Add the guidelines to the agent's working context; they apply only to this skill and only to the tools in toolMethodNames.

4. Follow the guidelines. Step 2 of this skill's guidelines says to call getPackageTracking with the tracking number, so call Invoke Tool with the skill's appId as providerAppId, the methodName from toolMethodNames, and the tracking number as the payload:

   Copy

5. Answer the user from the tool's response, following the remaining steps of the guidelines: report the status, the last known location and the estimated delivery date, or say that the number couldn't be found.

Quote a price for a customer abroad

A pricing app has declared three tools, convertCurrency, calculateVat and roundPrice, and an international-price-quote skill whose guidelines say in which order to use them. A store owner asks the agent "A customer in Germany wants the ceramic mug. What should I charge her?"

To quote a price with an app skill:

1. Call List App Skills with the site in context and pick the skill whose description, tags and examples match pricing for another country. Here, international-price-quote matches on its example "What should a customer in Germany pay for our $49 mug?".
2. Call Get App Skill with the skill's id to retrieve its guidelines. The guidelines list what the skill needs, the product's price and currency, the customer's country and a rounding style, and the order in which to call the tools.
3. Collect the inputs the guidelines ask for. The product price comes from the store, the country from the user's request, and the rounding style from the user or the skill's default.
4. Call Invoke Tool once per step in the order the guidelines dictate: convertCurrency to the customer's currency, calculateVat for the customer's country on the converted amount, then roundPrice on the total. Each call takes the previous response as its input.
5. Answer the user with the final price and the working, as the guidelines ask: the converted amount, the VAT added, and the rounded result.