Custom tools overview

A custom tool is an HTTP request your agent can make in the middle of a conversation: check a booking in your reservation system, look up a customer’s loyalty points, get the status of a repair ticket, or register a warranty claim. Knowledge covers facts you can write down; tools cover facts the agent must fetch live.

​

Where to find tools

Tools has no row in the sidebar. Click Agent, open an agent and go to its Actions tab. The Tools panel lists your tools with a switch for each, and its buttons lead to the rest:

• Manage tools (shown once you have a tool) opens the Tools page with your list.
• Add tool starts a new tool.
• Open marketplace opens the Tools showcase, where tools other Popcorn accounts shared can be added to yours.

​

What a tool is made of

For the full field-by-field walkthrough, see Create a custom tool.

​

What happens during a conversation

1. The agent reads the tool’s description and its parameter descriptions alongside everything else it can do, and decides on each message whether the tool fits.
2. It gathers the parameter values: from what the customer said, from the customer’s profile, or from the fixed value you configured. If a required value is missing, it asks the customer.
3. Popcorn sends the request to your URL with the configured method, headers, query string, path values and JSON body.
4. Your API’s JSON response is handed back to the agent, which uses it to write the reply in its own words.
5. If the request fails or your API returns an error, the agent receives the error instead of data and replies without the result.

In the Inbox, a reply that used a tool shows Used followed by the tool’s name under the message. Click Details to open Message source; Tool used names the tool. See Working with conversations.

​

What your API must support

​

An example

A repair shop wants the agent to answer “where is my repair?” from its ticketing system. When a customer writes “any news on ticket 482913?”, the agent recognises the request from the description, takes 482913 from the message, calls https://api.example-repairs.com/tickets/482913, and answers from the JSON that comes back.

​

Manage your tools

The Tools page lists one row per tool with its image (or initial), name and description. The ⋯ menu on a row offers Edit and Delete, and a Showcase column with an In showcase badge appears once you have shared a tool. The back link at the top reads Agents. The list shows tools that belong to the workspace; which agents use them is managed from each agent’s page, not here.

​

Tools and agents

A tool in the Tools list belongs to your workspace. To let an agent use it, switch it on in the Tools panel on the agent’s Actions tab and publish the agent; Popcorn then gives that agent its own copy of the tool, header values included. The tool does not need to be shared. Two consequences follow:

• To delete a tool, first switch it off in every agent that uses it and save those agents. Otherwise Couldn’t delete followed by the tool name appears with the line “If an agent uses this tool, turn it off in that agent’s Tools tab first.” (that is the Tools panel on the Actions tab).
• Editing a tool needs no disconnecting: the copies your agents hold are updated with it. A new URL, method or header value applies to the agents’ next calls. A new name, description or parameter set is part of each agent’s published version, so click Save and review and Publish changes on the agent for those to reach customers.

​

The showcase

The Tools showcase lists tools other Popcorn accounts have shared. You can add one to your workspace with Add to my tools and then fill in your own header values. Sharing your own tool has strict rules: it must call a reviewed public API host and carry no keys or fixed values. See Tools showcase.

​

Next steps