Extend the power of your BeDesk AI Agent by connecting it to your internal or third-party services with Tools. Tools allow your AI Agent to go beyond answering questions from its knowledge base by performing actions and retrieving live data from external APIs.
With Tools, your agent can:
Fetch a customer's order status from your e-commerce platform.
Retrieve user-specific information from your CRM.
Check appointment availability in a booking system.
And much more, by connecting to any service with an API.
This guide will walk you through creating and configuring a tool for your AI Agent.
You can find all your tools by navigating to AI Agent > Tools page from agent dashboard or admin area.
On this page, you can:
View Existing Tools: See a list of all created tools with their name, usage statistics, status, and last update date.
Activate or Deactivate Tools: From the Status column, you can activate or deactivate any tool. A deactivated tool will not be used by the AI Agent autonomously and will not be available for use in Flows.
Add New Tool: Click the + Add new tool button to begin creating a new integration.
Manage Agent Status: Use the Enable AI Agent toggle in the top-right to activate or deactivate the agent across your platform.
When you click + Add new tool, you'll be taken to the tool configuration screen, which is divided into four main sections: General, API connection, Test response, and Attribute mapping.
Configuration section will be disabled if previous section has errors or unsaved changes. Fix any errors, and click Save and continue button to move to next section.
This section defines the tool's purpose and how the AI Agent will decide to use it.
Name: Give your tool a clear, descriptive name. For example, "Fetch user orders".
Description: If you want this tool to be used outside of flows, clearly explain when the agent should use this tool, what it does, and what kind of data it retrieves. The AI uses this description to match the user's intent to the tool's capability.
Allow AI Agent to use this tool directly: This toggle controls how the tool is triggered.
Enabled: The AI Agent can intelligently decide to use this tool on its own during a conversation if the user's request matches the tool's name and description.
Disabled: The tool can only be activated when it is explicitly added as a step within a flow.
Here, you will configure the technical details for connecting to your external API.
Collect data inputs (optional): Specify any information the AI Agent needs to collect from the user before it can use the tool. For example, to fetch an order, you might need an order_id or customer_email. The agent will ask the user for this data if it's not already known.
API request:
Method: Select the appropriate HTTP method for your request (e.g., GET, POST, PUT DELETE).
HTTPS URL: Enter the full API endpoint URL. You can insert variables from collected inputs or user attributes here (e.g., https://api.my-shop.com/orders?customer_id={{user.id}}).
HTTP Headers: Add any necessary headers, such as Content-Type or an Authorization header for API keys.
Request body: If method is set to POST or PUT, you can enter JSON or plain text body for the request.
You can use any attributes available for the current user or flow, as well as data collected by AI agent as variables in url, headers or body.
This section allows you to verify your API connection and provide sample data for setting up the final step.
You have two options:
Live response: After configuring the API connection, click the Test request button to make a real call to your endpoint. The response from your API will be displayed here. This is the best way to ensure your connection is working correctly.
Example response: If your API is not yet live, or you want to configure the tool without making a live call, you can paste a sample JSON response into the editor. This allows you to complete the attribute mapping step.
In this final step, you can map data from the API response to specific BeDesk attributes. This is useful when the same tool is reused in multiple flows, this way you can use attributes mapped here in flows directly, without having to manually map them in each flow.
Mapping is optional and only used in flows. The AI Agent can understand and use all data returned from the API in its conversational responses automatically, even without mapping.
The system automatically parses the JSON response from the previous step and lists the available data fields. For each field, you can see:
Data: The path to the data point in the JSON structure. The [*] syntax indicates the tool is processing an array of items.
Example value: A sample value from the live or example response.
Format: The detected data type (e.g., String, Number, Boolean, Date).
Attribute mapping: An optional dropdown where you can select a BeDesk attribute to store this piece of data.
Once you have configured all the sections, click Save.
The tool will be set to inactive by default, which will prevent it from being selectable in flows or being used by AI agent. Make sure to set it to active from top right corner on this page.