> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # RunTool # Package: appTools # Namespace: ToolsProviderSpi # Method link: https://dev.wix.com/docs/api-reference/app-management/app-tools/tools-provider-v1/run-tool.md ## Introduction Runs a tool exposed by the service plugin. Wix calls this method when Aria invokes one of the tools declared in the app's [App Tools extension](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/app-tools/about-app-tools-extensions.md). Wix passes the tool's response back to Aria, and presents the result to the Wix user in natural language. > **Note:** Wix doesn’t check if the payload matches your `requestSchema` before calling your service plugin. Handle missing or unexpected fields in your implementation. Learn more about `requestSchema` in [App Tools extension](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/app-tools/about-app-tools-extensions.md). **Error handling:** If your implementation returns an error or times out, Aria continues the conversation without the tool result. --- ## REST API ### Schema ``` Method: runTool Description: Runs a tool exposed by the service plugin. Wix calls this method when Aria invokes one of the tools declared in the app's [App Tools extension](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/app-tools/about-app-tools-extensions.md). Wix passes the tool's response back to Aria, and presents the result to the Wix user in natural language. > **Note:** Wix doesn’t check if the payload matches your `requestSchema` before calling your service plugin. Handle missing or unexpected fields in your implementation. Learn more about `requestSchema` in [App Tools extension](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/app-tools/about-app-tools-extensions.md). **Error handling:** If your implementation returns an error or times out, Aria continues the conversation without the tool result. URL: null Method: POST Method parameters: param name: methodName | type: methodName | description: Identifies which tool to run. Matches the `methodName` of an active tool declared in the app's [App Tools extension](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/app-tools/about-app-tools-extensions.md). | validation: minLength 1, maxLength 50 param name: payload | type: payload | description: Input data for the tool as a JSON object. The shape corresponds to the tool's `requestSchema` in the [App Tools extension](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/app-tools/about-app-tools-extensions.md), but isn't validated by the platform before the call. Return type: RunToolResponse - name: response | type: object | description: Output data returned by the tool as a JSON object. The schema should correspond to the tool's `responseSchema` in the [App Tools extension](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/app-tools/about-app-tools-extensions.md). ``` ### Examples ### Run a custom AI tool Shows the request that Wix sends to your service plugin endpoint when the AI assistant invokes a tool, and the expected response format. ```curl curl -X POST \ 'https://your-app.com/v1/run-tool' \ -H 'Authorization: ' \ -H 'Content-Type: application/json' \ -d '{ "methodName": "get-product-recommendations", "payload": { "customerId": "d7a341c4-196b-46e7-813c-2b0fc1847ec6", "category": "electronics", "limit": 5 } }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.appTools.toolsProvider.runTool(request, metadata) Description: Runs a tool exposed by the service plugin. Wix calls this method when Aria invokes one of the tools declared in the app's [App Tools extension](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/app-tools/about-app-tools-extensions.md). Wix passes the tool's response back to Aria, and presents the result to the Wix user in natural language. > **Note:** Wix doesn’t check if the payload matches your `requestSchema` before calling your service plugin. Handle missing or unexpected fields in your implementation. Learn more about `requestSchema` in [App Tools extension](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/app-tools/about-app-tools-extensions.md). **Error handling:** If your implementation returns an error or times out, Aria continues the conversation without the tool result. Method parameters: param name: metadata | type: Context | description: this message is not directly used by any service, it exists to describe the expected parameters that SHOULD be provided to invoked Velo methods as part of open-platform. e.g. SPIs, event-handlers, etc.. NOTE: this context object MUST be provided as the last argument in each Velo method signature. Example: ```typescript export function wixStores_onOrderCanceled({ event, metadata }: OrderCanceledEvent) { ... } ``` - name: requestId | type: string | description: A unique identifier of the request. You may print this GUID to your logs to help with future debugging and easier correlation with Wix's logs. - name: currency | type: string | description: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-letter currency code. | validation: format CURRENCY - name: identity | type: IdentificationData | description: An object that describes the identity that triggered this request. - ONE-OF: - name: anonymousVisitorId | type: string | description: GUID of a site visitor that has not logged in to the site. | validation: format GUID - name: memberId | type: string | description: GUID of a site visitor that has logged in to the site. | validation: format GUID - name: wixUserId | type: string | description: GUID of a Wix user (site owner, contributor, etc.). | validation: format GUID - name: appId | type: string | description: GUID of an app. | validation: format GUID - name: languages | type: array | description: A string representing a language and region in the format of `"xx-XX"`. First 2 letters represent the language code according to ISO 639-1. This is followed by a dash "-", and then a by 2 capital letters representing the region according to ISO 3166-2. For example, `"en-US"`. - name: instanceId | type: string | description: The service provider app's instance GUID. | validation: format GUID param name: request | type: RunToolRequest - name: methodName | type: string | description: Identifies which tool to run. Matches the `methodName` of an active tool declared in the app's [App Tools extension](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/app-tools/about-app-tools-extensions.md). | validation: minLength 1, maxLength 50 - name: payload | type: object | description: Input data for the tool as a JSON object. The shape corresponds to the tool's `requestSchema` in the [App Tools extension](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/app-tools/about-app-tools-extensions.md), but isn't validated by the platform before the call. Return type: PROMISE - name: response | type: object | description: Output data returned by the tool as a JSON object. The schema should correspond to the tool's `responseSchema` in the [App Tools extension](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/app-tools/about-app-tools-extensions.md). ``` ### Examples ### runTool ```javascript import { toolsProvider } from '@wix/app-tools/service-plugins'; async function runTool(request,metadata) { const response = await toolsProvider.runTool(request,metadata); }; ``` ### runTool (with elevated permissions) ```javascript import { toolsProvider } from '@wix/app-tools/service-plugins'; import { auth } from '@wix/essentials'; async function myRunToolMethod(request,metadata) { const elevatedRunTool = auth.elevate(toolsProvider.runTool); const response = await elevatedRunTool(request,metadata); } ``` ### runTool (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { toolsProvider } from '@wix/app-tools/service-plugins'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { toolsProvider }, // Include the auth strategy and host as relevant }); async function runTool(request,metadata) { const response = await myWixClient.toolsProvider.runTool(request,metadata); }; ``` ---