Tools Host: 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.

Run an app's tool for a site owner

A shipping app installed on the site declares a getPackageTracking tool. The site owner asks an agent "Where is shipment 1Z999AA10123456784?", and the agent answers with the app's tool.

To run an app's tool:

1. Call List Tools Providers with the site in context. The response lists each installed app that exposes tools, with every tool's methodName, description, requestSchema and the site's settings.

2. Pick the tool whose description matches the request, and skip any app or tool whose settings.enabled is false. Here, getPackageTracking on the shipping app matches.

3. Build the payload from the tool's requestSchema. The schema requires trackingNumber, which the owner gave in the request.

4. Call Invoke Tool with the app's appId as providerAppId, the tool's methodName, and the payload:

   Copy

5. Answer the owner from response, which is whatever the app returned: here the status, last known location and estimated delivery date.

Switch an app's tool off for a site

A site owner wants agents to keep tracking packages with the shipping app, but never to send notes to the carrier through it. The owner turns that one tool off for the site while leaving the rest of the app's tools on.

To switch a single tool off:

1. Call List Tools Providers to find the app's appId and the methodName of the tool to disable. Here, the shipping app's sendCarrierNote.

2. Call Set Tools Toggle with the app's ID as providerAppId and the tool with enabled set to false. Tools not listed keep their current setting:

   Copy

3. Call List Tools Providers again to confirm: the tool is still listed, with settings.enabled set to false. From now on, Invoke Tool rejects it with TOOL_DISABLED, while the app's other tools keep working.

4. To switch the whole app off instead, call Set Tools Providers Toggle with the app's ID and enabled set to false. Invoke Tool then rejects every tool of the app with PROVIDER_DISABLED.