Copilot Tool Definition

What is a Tool?

A tool is an external function, API, or action that your Fynd Kaily AI agent can call during a conversation. Instead of only generating text, the agent can use tools to fetch data, run computations, or interact with your systems—for example, looking up a customer by email, creating a calendar event, or calling an API.

Copilot tool definitions specify these external functions so that Copilot's LLMs can access external data, perform specific computations, or interact with the environment.

How Tools Work with Fynd Kaily AI Agent

When a user asks something that needs a tool (e.g., "Schedule a meeting for tomorrow"), the Fynd Kaily AI agent decides which tool to use, sends the right inputs, and your workflow runs. The workflow result is sent back to the agent, which then responds to the user. Tools are configured inside a workflow and connected to your agent via a CopilotWebhook Trigger and a Switch Activity, so each tool name maps to a branch in your workflow.

Parts of a Tool Definition

A tool definition in Fynd Kaily includes:

Part	Description
Tool Name	The name used to trigger this tool from the workflow (e.g., create_event).
Active Status	Whether the tool is turned on and available to the agent.
Host ID Authentication	Whether the tool requires Host ID (authenticated user) to run.
Tool Description	A short explanation of what the tool does. The agent uses this to choose when to call the tool.
Tool Parameters	Inputs the tool needs. Each parameter has: Parameter Name, Parameter Description, Required (yes/no), Data Type (e.g., string, number, boolean), and Applicable Surfaces. A tool can have multiple parameters.
Allowed Surfaces	The surfaces (e.g., Public Webpage, Web Widget) where this tool is visible and can be used.

How Tool Definitions Work

To use a tool, the following prerequisites must be met:

• A Copilot workflow must start with a CopilotWebhook Trigger.
• The trigger can be followed by single input and output workflow activities, such as APIs or functions that may act as middleware.
• The workflow must include a Switch Activity, connected to the tool definitions.
• When a tool is triggered by Copilot, it sends the following payload:

{
    "payload": {
                        "event": "tool_name_to_be_triggered",
                        "copilotInputArgs": {
                            "param1": "string/int/bool"
                        },
                        "copilotAppId": "string",
                        "organizationId": int,
                        "threadId": "string",
                        "copilotUser": {
                            "id": "string",
                            "copilotAppId": "string",
                            "name": "string",
                            "email": "string",
                            "phone": "string",
                            "profilePicUrl": "string",
                            "hostId": "string",
                            "verified": bool,
                            "meta": {
                                "additionalFields": {}
                            },
                            "surfaces": [
                                "web"
                            ],
                            "device": {
                                "host": "script.copilot.live",
                                "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
                                "appVersion": "5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
                                "languages": [
                                    "en-US",
                                    "hi",
                                    "en"
                                ],
                                "platform": "MacIntel"
                            },
                            "organizationId": int,
                            "createdAt": "2024-12-12T15:20:23.764Z",
                            "updatedAt": "2024-12-19T06:17:03.074Z"
                        },
        "conversationContext": {}
    }
}

• The Switch Activity runs the right Copilot tool based on the payload.event field.
• Input arguments are in payload.copilotInputArgs.
• The last node that runs in the workflow marks the end of the tool call. Whatever that node returns is the result sent back to the Fynd Kaily AI agent.

Drag the AI Agent Tool Definition into the workflow.

Configure Your Tool in Fynd Kaily

1. Configure the Tool

Click on the tool node to open the settings drawer. Here, you need to define how the tool will operate:

• Select Tool Call as the Resource. This links the tool to Copilot’s functionality.

• Choose the Operation as Add Tool Definition to enable configuration for creating a new tool.

  Configure the AI Agent Tool Definition settings.

2. Activate and Add Authentication

To make the tool usable in your Fynd Kaily AI agent, enable the toggle Activate Tool. To allow only signed-in users to use it, enable Authenticated Access Only (Host ID authentication).

Activate the tool to make it usable in your AI Agent.

3. Provide Tool Description

Provide a short description of what the tool does. For example: "This tool retrieves a list of customers by their email address." The Fynd Kaily AI agent uses this to decide when to call the tool.

Provide a description to clarify the tool's purpose.

note

A description is required to save the tool configuration.

4. Add Parameters (Optional)

Parameters are the inputs the tool needs. For each parameter set: Name, Description, Data type (e.g. string, number, boolean), and Required (yes/no).

Set parameters for the tool if needed.

info

You can add multiple parameters as needed.

5. Supported Surfaces

Choose where the tool is available by selecting one or more surfaces (e.g. Public Webpage, Web Widget, Whatsapp, Slack, Mobile). The tool will only run on the surfaces you select.

Select the surfaces where the workflow can be deployed.

Select the surfaces where the workflow can be deployed.

6. Test Your Tool

After configuration, click Next to open the Test screen and verify that your tool works as expected.

The final AI Agent Tool Definition setup in the workflow.

The final AI Agent Tool Definition setup in the workflow.

The final AI Agent Tool Definition setup in the workflow.

---

Workflow Example (Creating an Event in Google Calendar with Fynd Kaily)

This example shows how to add a tool to your Fynd Kaily AI agent so users can create Google Calendar events from a conversation.

Steps to Create a Workflow for Adding Events to Google Calendar

1. Add the Copilot Tool Node

   • Drag the Copilot Tool node into your workflow and rename it to create_event.

     Rename the AI Agent Tool Node.

   • Configure the Resource as Tool Call and select the Operation as Add Tool Definition.

   • Toggle Activate Tool and provide a tool description, e.g., "Creates an event in Google Calendar."

     Activate the AI Agent Tool and provide a description.

---

2. Define Parameters (Optional)

   • email_id: "Email ID of the event attendees."

     Define parameters for the tool.

   • subject: "Subject/Title of the event to be scheduled"

     Define parameters for the tool.

   • description: "Brief description or details of the event."

     Define parameters for the tool.

---

3. Set Supported Surfaces

   • Select the surfaces where the tool will operate (e.g., Public Webpage, Web Widget, Whatsapp, Slack).

     Select surfaces for the workflow.

---

Once you’ve selected the supported surfaces, add a Google Calendar node and use the tool parameters in it (retrieve arguments) as follows.

4. Add and Configure the Google Calendar Node

   • Search for Google Calendar in the left panel and drag it into the workflow.

   Drag the Google Calendar node into the workflow.

   • Open the settings drawer for the Google Calendar node and connect your Google account.

   Connect your Google account in the settings drawer.

   • Set the Operation to Create Event.

   Select the Create Event operation.

---

5. Use Tool Parameters in the Node (Retrieve Arguments)

   To pass the user's input from the Copilot Tool into the Google Calendar node, use in the node's fields. This is called retrieving arguments.

   • Event Summary: Use the subject/title provided by the user:

   Reference the event subject via payload.

   • Event Description: Use the description provided by the user:

   Reference the event description via payload.

   • Location: Enter or reference the venue for the event.

   Location field for the event.

   • Attendees: Use the email IDs provided by the user:

   Use dynamic inputs for attendees' email IDs.

   • Start Date and End Date: Set the event timing.

   Specify start and end dates for the event.

   Understanding Payload

   A payload is the data passed through the workflow. In Copilot workflows, you access it using curly braces . The values the user supplies when they trigger the tool are in payload.copilotInputArgs.

   Key	Description
   payload	The data transferred within the workflow.
   copilotInputArgs	The input arguments provided by the user through the Copilot Tool (e.g. subject, description, email_id).

---

6. Save and Test

   • Save the workflow, click Publish, and run a test to confirm the event is created in Google Calendar.

   Test the workflow to confirm successful event creation.

---

7. Create an Event from the Copilot Interface

   • In your Copilot (AI Agent) interface, ask it to create an event.

   • When prompted, provide Summary, Description, and Email ID.

   • The workflow runs and schedules the event in Google Calendar.

   • Check Google Calendar to verify the event was created.

   Confirm the event in Google Calendar.

   • You can view execution history, select the version, and check the result and body for details.

   View execution history, result, and body for the workflow.