Skip to main content

​
Creating the tools

A tool is a function that an agent can use to carry out actions like calling external APIs or looking up information in a data source, as part of following the instructions defined in the prompt. In this tutorial, we will create five Tools to interface with our Shopify proxy-service APIs and data sources. If you are using the built-in Syllable Shopify Tools, you can skip this step. Before we begin you will need:
  • Your Shopify store name (id)
    • You should replace the “replace-this” in each of the tools with your Shopify store name (id)
  • Your proxy-service URL and endpoints
As we create Tools, replace the store_name and endpoint URLs with your versions of both. Click “Tools” on the left sidebar. This will take you to a list of the existing tools for your org. You’ll notice that there are many existing already - this is because Syllable comes with a standard set of tools out of the box. To create a new one, click “New tool” in the top-right corner.

​
get_shopify_order_by_number

This tool will use an order_number to retrieve order information from the Shopify API. Use the following tool schema to create your tool. Replace the endpoint url with your own service’s URL (or keep ours to test your tool), and the default static parameter value for store_name with your Shopify store name. 
{
  "type": "endpoint",
  "tool": {
    "type": "function",
    "function": {
      "name": "get_shopify_order_by_number",
      "description": "Get an order by order number from Shopify API via proxy service.",
      "parameters": {
        "type": "object",
        "properties": {
          "order_number": {
            "type": "string",
            "description": "A unique integer called the order number, different than the confirmation number string."
          }
        },
        "required": [
          "order_number"
        ]
      }
    }
  },
  "endpoint": {
    "url": "https://gpqvijqyrf.us-east-2.awsapprunner.com/shopify/order-by-number",
    "method": "get",
    "argumentLocation": "query"
  },
  "defaults": null,
  "staticParameters": [
    {
      "name": "store_name",
      "description": "Unique shopify store ID.",
      "required": true,
      "type": "string",
      "default": "replace-this"
    }
  ],
  "result": null
}

​
get_shopify_order_by_email_confirmation

This tool will retrieve order information using a combination of order confirmation number and the user email address. Use the following schema to create your tool. Replace the endpoint url with your own service’s URL (or keep ours to test your tool), and the default static parameter value for store_name with your Shopify store name. 
{
  "type": "endpoint",
  "tool": {
    "type": "function",
    "function": {
      "name": "get_shopify_order_by_email_confirmation",
      "description": "Get an order by email and confirmation number from Shopify API via proxy service.",
      "parameters": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "description": "The users email address used to place the order."
          },
          "confirmation_number": {
            "type": "string",
            "description": "A unique alphanumeric string called the confirmation number, different than the order number integer."
          }
        },
        "required": [
          "email",
          "confirmation_number"
        ]
      }
    }
  },
  "endpoint": {
    "url": "https://gpqvijqyrf.us-east-2.awsapprunner.com/shopify/order-by-confirmation-number-and-email",
    "method": "get",
    "argumentLocation": "query"
  },
  "defaults": null,
  "staticParameters": [
    {
      "name": "store_name",
      "description": "Unique shopify store ID.",
      "required": true,
      "type": "string",
      "default": "replace-this"
    }
  ],
  "result": null
}

​
get_shopify_products

This tool will retrieve product information using either product_id or a search term (product_name). Use the following schema to create your tool. Replace the endpoint url with your own service’s URL (or keep ours to test your tool), and the default static parameter value for store_name with your Shopify store name. 
{
  "type": "endpoint",
  "tool": {
    "type": "function",
    "function": {
      "name": "get_shopify_products",
      "description": "Get a list of products from Shopify API via proxy service by product_id or a product keyword search.",
      "parameters": {
        "type": "object",
        "properties": {
          "product_name": {
            "type": "string",
            "description": "A keyword to search for products in the store via product title."
          },
          "product_id": {
            "type": "string",
            "description": "A unique ID to search for a specific product in the store."
          }
        },
        "required": []
      }
    }
  },
  "endpoint": {
    "url": "https://gpqvijqyrf.us-east-2.awsapprunner.com/shopify/products",
    "method": "get",
    "argumentLocation": "query"
  },
  "defaults": null,
  "staticParameters": [
    {
      "name": "store_name",
      "description": "Unique shopify store ID.",
      "required": true,
      "type": "string",
      "default": "replace-this"
    }
  ],
  "result": null
}

​
general_shopify_store_information

This tool will be used to access the data source we created to answer general questions about the store and its policies. Be sure the default static parameter value matches the name of your data source. Do not change the helix search URL. 
{
  "type": "endpoint",
  "tool": {
    "type": "function",
    "function": {
      "name": "general_shopify_store_information",
      "description": "Look up general information about the store from data sources. Returns an answer and a reference URL. Do not include the reference URL in the spoken response.",
      "parameters": {
        "type": "object",
        "required": [
          "question"
        ],
        "properties": {
          "question": {
            "type": "string",
            "description": "A user inquiry about content in the agent's documents, e.g., What is your return policy?"
          }
        }
      }
    }
  },
  "endpoint": {
    "url": "http://helix-app/v1/search",
    "method": "post",
    "argumentLocation": "body"
  },
  "defaults": null,
  "staticParameters": [
    {
      "name": "doc",
      "description": "Data sources to which the tool should have access",
      "required": true,
      "type": "data_source_list",
      "default": [
        "store_faq"
      ]
    }
  ],
  "result": null
}

​
get_shopify_product_url

This tool will use a provided product_handle to programmatically generate the URL to view a product in your Shopify store. Use the following tool schema to create your tool. Replace the endpoint url with your own service’s URL (or keep ours to test your tool), and the default static parameter value for store_name with your Shopify store name. 
{
  "type": "endpoint",
  "tool": {
    "type": "function",
    "function": {
      "name": "get_shopify_product_url",
      "description": "Get an order by order number from Shopify API via proxy service.",
      "parameters": {
        "type": "object",
        "properties": {
          "product_handle": {
            "type": "string",
            "description": "Unique shopify product identifier. Examples 'jeans', 'polo-shirt-1'"
          }
        },
        "required": [
          "product_handle"
        ]
      }
    }
  },
  "endpoint": {
    "url": "https://gpqvijqyrf.us-east-2.awsapprunner.com/shopify/get-product-url",
    "method": "get",
    "argumentLocation": "query"
  },
  "defaults": null,
  "staticParameters": [
    {
      "name": "store_name",
      "description": "Unique shopify store ID.",
      "required": true,
      "type": "string",
      "default": "replace-this"
    }
  ],
  "result": null
}
We have one more step before we’re able to create the agent, and that’s to add a greeting message for the agent to deliver to the user at the beginning of a conversation. Click “Create a message” to continue the tutorial. (Full tools docs)
⌘I