Before you start
- The API endpoint: an
https://address, the method, and which values it expects in the path, query string, or body. - Any key or token the API needs, to put in a header. Keys go in Headers, never in the URL.
- A clear sentence about when the agent should use the tool. You will put it in Description.
Open the form
Click Agent in the sidebar, open an agent, go to its Actions tab and click Add tool in the Tools panel. If you already have tools, you can also click Manage tools and then New tool, or press g then t to reach the Tools page. The New tool page has the form in the main column and Start from API docs beside it (above the form on a narrow screen).Optional: start from the API documentation
Start from API docs can fill the form for you from a public documentation page.1
Paste the documentation link
Under Documentation link, enter the address of the docs for one endpoint (“Paste a link to the docs for one endpoint and we fill in the form.”) and click Fill in from docs. The page must be publicly reachable; local or private addresses, and addresses with a username and password, are refused.
2
Wait for the result
Reading the docs takes up to a minute. When it finishes you see Filled in from the docs. Check the details before you create the tool. and the name, description, method, URL, headers and parameters are filled in. Every
{placeholder} in the URL gets a parameter of its own.3
Review everything
Check each field against the documentation. Placeholders such as
Bearer <token> in Headers must be replaced with your real value, and parameters the reader guessed may need better descriptions.Details
Request
1
Method and URL
Choose the Method (
GET, POST, PUT, DELETE) and enter the URL. For values that belong in the path, use curly braces: https://api.example.com/tickets/{ticketId}. Do not add keys to the URL; define query parameters instead.2
Headers
Click Add header for each header and fill in its Name and Value, for example
Authorization and Bearer sk_live_…. Values are hidden as you type; Show values and Hide values toggle them in browsers that can hide them. Remove header deletes a row.3
Query parameters
Click Add query parameter for each value that goes in the query string (“Values your agent fills in and sends in the URL.”). Path values written as
{name} in the URL are defined here too: give the parameter the same name and it is marked In the URL.4
Body parameters
For any method other than
GET, the Body parameters panel appears. Click Add body parameter for each field of the JSON body (“Values your agent fills in and sends in the request body.”). If you switch to GET, body parameters are not saved, and the Method field warns you: “Body parameters aren’t saved for GET requests. Switch to POST or PUT to keep them.”Parameter fields
Where the value comes from
Each parameter has a Where the value comes from setting that decides how its value is found at call time:
A line under the parameter restates the choice in plain words, for example “Filled from the customer’s email. If it’s missing, your agent asks the customer.”
Tools created through an AI assistant can also use Customer details, which fills the value from the customer’s details when they do not give one in the chat. The form shows that source but does not offer it.
Create the tool
As soon as you type, a bar across the top reads Unsaved changes with Discard and Create tool. Click Create tool. Checks run first; if something needs fixing you see Fix N fields to save, the first problem is highlighted, and each one says what to do:
On success you see Tool created and the page for the new tool opens, where later changes are saved with Save changes.
Header values are hidden after saving. When you reopen a tool, a header with a stored value shows Saved. Leave blank to keep it. in its Value field. Leave it blank to keep the stored value, type a new value to replace it, or remove the row to clear it. The name is matched regardless of capitalisation, so retyping
x-api-key for a stored X-API-Key keeps the value.Edit a saved tool
Open the tool from the Tools page (click its row, or ⋯ then Edit), change what you need, and click Save changes in the bar that appears (“Tool saved” confirms it). You can edit a tool while agents have it switched on: the tool is updated in place, and every copy your agents hold in this workspace is updated with it. A header value you type applies to those copies too; a value you leave blank stays as each copy has it stored. 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. A tool you have shared in the showcase stays shared, and saving also refreshes its showcase copy. If that refresh fails you see Tool saved, but its showcase copy wasn’t updated; see Tools showcase.Connect the tool to an agent
1
Open the agent
Click Agent in the sidebar and open the agent that should use the tool.
2
Switch the tool on
On the Actions tab, find your tool in the Tools panel (“Actions you set up yourself or add from the marketplace.”) and switch it on. The tool does not need to be shared.
3
Publish
Click Save and review, then Publish changes. Until you publish, live conversations do not have the tool. See Test and publish. If a tool could not be enabled, saving shows Couldn’t turn on … Your other changes were saved.; switch the tool on again and click Save and review.
Test it
- Publish the agent with the tool switched on. The test chat uses the published version.
- Open the Test your agent panel (or Test agent on a narrower screen) and ask for something only the tool can answer, the way a customer would: Where is my repair? Ticket 482913. Under the reply, Used followed by the tool’s name shows that it ran.
- Check the reply against your system, then open the conversation in the Inbox and click Details next to the tool name. Message source shows the Tool used.
https:// with no keys in the query string and no username or password in it, that it is not a private or internal address, that the header value is correct, and that your API returns JSON.