Copilot Tool

Copilot tool definitions specify external functions, APIs, or actions that a model can call to extend its capabilities beyond text generation. These tools enable Copilot's LLMs to access external data, perform specific computations, or interact with the environment.

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 executes a specific Copilot tool based on the payload.event field.
Input arguments are present inside payload.copilotInputArgs.

Drag the Copilot Tool Definition into the workflow.

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 Copilot Tool Definition settings.
Activate and Add Authentication (Optional)

To make the tool usable in workflows, enable the toggle Activate Tool. If you want to limit its access to authenticated users, enable Authenticated Access Only. This ensures the tool is secure and available only to authorized individuals.

Activate the tool to make it usable in your Copilot.
Provide Tool Description

When configuring a tool, the first step is to provide a description that clearly outlines its purpose. For example, "This tool retrieves a list of customers by their email address." This description is essential because it helps the Copilot AI to understand the tool’s function.

Provide a description to clarify the tool's purpose.

note
A description is mandatory to save the tool configuration.

Add Parameters (Optional)

Parameters are inputs that the tool requires to perform its task. For example, a tool fetching customer details might require the customer’s email address as a parameter. Configuring parameters involves:
- Naming the parameter to identify it uniquely.
- Providing a Description to explain what the parameter is used for. The description is essential because it helps the Copilot AI understand the purpose of the parameter and how to use it effectively in workflows.
- Choosing the data type (e.g., string, number, boolean) to ensure correct input.
- Marking parameters as required or optional, depending on their importance.
  
  note
  You can add multiple parameters to accommodate various inputs as required.
  
  Set parameters for the tool if needed.
Supported Surfaces

Specify where the workflow should be accessible by selecting one or more surfaces. Surfaces define the contexts or platforms where the tool will be functional.
- For example, if you select "Public Webpage," the workflow will only operate on webpages and not in other environments like Web Widget, Phone call, or WhatsApp.
- This makes sure the tool works properly on the selected platforms.
  
  Select the surfaces where the workflow can be deployed.
Save Your Tool

Once all configurations are complete, click the Save button. This adds the tool to your workflow and makes it available for use. Ensure that all mandatory fields, such as the description, are filled before saving.

The final Copilot Tool Definition setup in the workflow.

Workflow Example (Creating an Event in Google Calendar through Copilot)

This example demonstrates how to create a workflow for adding events to Google Calendar using the Copilot Tool.

Steps to Create a Workflow for Adding Events to Google Calendar

Add the Copilot Tool Node
- Drag the Copilot Tool node into your workflow and rename it to create_event.
  
  Rename the Copilot 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 Copilot Tool and provide a description.

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.

Set Supported Surfaces
- Select the surfaces where the tool will operate (e.g., Public Webpage, Web Widget).
  
  Select surfaces for the workflow.

Once you’ve selected the supported surfaces, the next step is to connect a Google Calendar node to integrate calendar functionality into your workflow. This allows the workflow to interact with Google Calendar for scheduling, event management, or related tasks.

Workflow Example (Creating an Event in Google Calendar through Copilot)​

Steps to Create a Workflow for Adding Events to Google Calendar​

Workflow Example (Creating an Event in Google Calendar through Copilot)

Steps to Create a Workflow for Adding Events to Google Calendar