How to connect your agent to other systems with an HTTP tool

Create, test and troubleshoot an HTTP tool so your AI agent can check or send data to your own systems during a conversation, through an API. Includes the technical reference and answers to common problems.

Last updated 20 days ago

An HTTP tool lets your agent interact with other systems (internal or external) during a conversation: check availability in your calendar, look up a customer in your CRM, or send an order to a webhook in n8n, Make, Zapier or GoHighLevel. You set up the endpoint once, and the agent decides when to call it and which data to send.

This guide has three parts: how to create the tool, a technical reference, and answers to the most common problems.

Before you start: Have the endpoint URL and, if it asks for one, its token or API key. These tools can only be created or edited by users with an Owner or Admin role in the agency or subaccount; users with an User role can only see them.

Step 1: Open Custom Tools in your agent

In the left menu, open Agents and select your agent. Open Integrations, then Custom Tools and HTTP Tools. Click Create & Assign HTTP Tool: the tool is created and assigned to this agent.

Step 2: Describe the tool

In New HTTP Tool, fill in:

Tool Name: a short name in snake_case, for example check_availability. It must be unique and can't repeat the name of another tool the agent uses.
Description: what the tool does.
Endpoint URL and the Method: GET, POST, PUT, PATCH or DELETE. If part of the URL is dynamic, write it between braces, for example /clients/{id}.
Prompt Instructions: when and how the agent should call the tool, and which data it must capture first.

Important: The agent reads Prompt Instructions to decide when to call the tool. Be specific about the circumstances where warranted and the data it must ask for, or the tool may run at the wrong time or not at all.

Step 3: Declare the parameters

In Parameters, declare every piece of data the agent sends. Use Body Parameters for data sent in the request body (POST, PUT, PATCH) and Query Parameters for data added to the URL.

Add parameters by clicking on Add and fill in the name, the type, whether it's Required, and a description.

To paste a full schema, switch from Form to JSON, and insert it in the enabled text box. For example:

{
  "type": "object",
  "required": ["payment"],
  "properties": {
    "payment": {
      "type": "object",
      "description": "Payment receipt data",
      "required": ["amount", "date"],
      "properties": {
        "amount": { "type": "number", "description": "Amount paid" },
        "date": { "type": "string", "description": "Payment date (YYYY-MM-DD)" },
        "reference": { "type": "string", "description": "Reference number" }
      }
    }
  }
}

Important: The tool only sends the fields you declare. If the agent knows a piece of data but it isn't declared here, it never reaches your system.

If the system asks for authentication, open Advanced Options and choose the Authentication type: Bearer Token, Basic Auth or API Key. Add any extra headers in Custom Headers.

Step 4: Test the endpoint

Open Test endpoint, fill in sample values and click Run test. It sends one real request with the form’s content, exactly as the agent would build it, and shows the status, the time and the response.

Important: The test is a real request. If the tool creates or changes something, like a booking or an order, the test does it too. Use distinguishable test data.

Step 5: Create the tool and try it

Click Create Tool. The tool appears in the list as Active. Then open Test Agent and ask something that should trigger it: the chat shows each call and its result, in green if it worked and in red if it failed.

Which tools each agent uses

An agent uses the HTTP tools created and assigned in it with Create & Assign HTTP Tool, plus the tools in the toolkits assigned to it. See How to group tools in a toolkit.
The switch on each tool turns it on or off for every agent that uses it.
You'll find all your HTTP tools in the navigation panel at the left, Agents sub menu, in Custom Tools. From there you can add one with Add HTTP Tool, edit it, turn it on or off, or delete it with the trash icon.

Technical reference

How the request is built

Path parameters: each {name} in the URL is replaced with the value the agent sends, URL-encoded.
Query parameters: added to the URL as ?key=value.
Body parameters: sent as JSON, with only the declared fields.
Headers: your Custom Headers plus the authentication you chose.

How to declare parameters

Types: string, number, integer and boolean in Form view. In JSON view you can also use object, array and a list of allowed values (enum).
Description: every field needs one, including fields inside other objects. It's what the agent reads to know which value to put there, so write it as an instruction: "Appointment date in YYYY-MM-DD format".
Required: required fields are always sent. The agent can leave out the others if it doesn't have the data.
Match the type to the data: if a field is a number, declare it as number. If the agent sends a number to a field declared as string, the call is rejected and the tool doesn't run.

Limits

Response time: the agent waits up to 30 seconds. If your system doesn't answer in time, the agent is told the service didn't respond and continues the conversation.
Response size: the agent reads up to 50 KB of the response. Return only the data it needs.
Errors: if your system answers with an error (4xx or 5xx), the agent receives the status code and part of the error message, and continues the conversation.
Test endpoint: shows up to 10 KB of the response.

Security

The URL must be reachable from the internet. Private or internal addresses (localhost, 127.x, 10.x, 172.16–31.x, 192.168.x, 169.254.x) are blocked, also when a public URL redirects to them.
Tokens, passwords and API keys are stored encrypted and never shown again after you save. When you edit a tool, the fields look empty: leave them empty to keep the saved value, or type a new one to replace it.

Common problems

My system only receives part of the data

The tool only sends the fields declared in its parameters. Add the missing fields, with their type and description, in Body Parameters or Query Parameters. For nested data, use the JSON view.

I can't save the tool

Check that every field, including the ones inside other objects, has a name, a type and a description, and that the JSON is valid. A malformed JSON can't be saved.

The agent doesn't call the tool

Check that the tool is Active and that it's assigned to the agent, directly or through a toolkit.
Make Prompt Instructions more specific: when to call it and which data it needs first.
Check the types: if a value doesn't match its declared type, the call is rejected. Look at the call in Test Agent to see the error.

The test fails or the URL is blocked

Check the URL for typos and extra spaces, especially at the start.
Use a public URL. Local or internal addresses are blocked.
Check the authentication type and the credentials.
If it times out, check that your system answers in less than 30 seconds.

The tool runs but the agent gives a wrong answer

Run the test and read the response. If it's very long or full of data the agent doesn't need, return a shorter response from your system, and tell the agent in Prompt Instructions which fields to use.

Done

Your agent can now use the tool in its conversations. Test it again after every change to the tool or to the prompt.

Need help? Contact support from your platform's home view. Include the tool name and what you see in Test endpoint or in Test Agent.

Was this helpful?

Still need help? Share an idea