Skip to main content
Agent Tools and Actions

Create a Custom HTTP Tool

Let your agent call any public HTTPS API during a call: look up a record, create a ticket or add a note. Set the endpoint, the request and where each value comes from.

Written By voiceaiwrapper

Last updated 26 days ago

A custom HTTP tool lets your agent call your own systems while a caller is on the line. It can look up a booking in your CRM, open a support ticket or add a note to a patient record. You describe the request once in your Pod (an engine or provider connection). Then you attach the tool to any agent that needs it.

This article covers the Setup tab: what the tool is called, which API it calls and what goes into each request. The Response, Safety and Test tabs each have their own article, linked at the end.

Applies to: agents in a VAW Native Pod. On Vapi, Retell AI and ElevenLabs, tools are built in your provider account. See Provider Knowledge Bases and Tools in VoiceAIWrapper.

Before you start

  • The API's documentation. You need the endpoint URL, the HTTP method and the fields the API expects.
  • A public HTTPS endpoint. Tools only call addresses that start with https:// and are reachable from the internet.
  • The API key, if the API needs one. Store it as a connection first, or add one from the Setup tab. See Store API Keys with Tool Connections.

Step 1: Start a new tool

  1. In your VAW Native Pod, open Tools in the sidebar.
  2. Click New tool.
  3. Choose Custom HTTP tool.

The tool page opens on the Setup tab. You'll also see Response, Safety and Test. The Usage tab appears once the tool is saved.

Step 2: Name and describe the tool

Under What it does:

  • Name: a short name, such as "Add call note to chart". When you attach the tool, the agent's function name is based on it.
  • Description: what the tool does and when it fits, in up to 2,000 characters. The agent reads this text word for word to decide when to use the tool, so write it for the agent: "Adds a short note to the patient record. Use it to record what was agreed on the call."

Step 3: Choose a connection

Under Connection, pick the stored key this API needs, or leave it on No connection for an open API. Only Bearer token and Custom header connections appear here. Click Add a connection to create one without leaving the page.

The connection adds its own header to every request. You don't add an Authorization header yourself, and the key is never shown in the request.

Connections are shared by every Pod in your organization. Replacing a connection's key changes the next request of every tool that uses it, not only this one.

If the API refused the connection's key the last time a test used it, you'll see a red alert under Connection. The tool can't run until the key is replaced in the Connections sheet.

Don't type an API key as a header value. A typed value is stored with the tool and carried into every call. A connection keeps the key encrypted and private.

Step 4: Set the method and endpoint

Under The request:

  1. Choose the Method: GET, POST, PUT, PATCH or DELETE.
  2. Enter the Endpoint, for example https://api.example.com/v1/patients/{patient_id}/notes.

You can put two kinds of placeholder in the path of the URL:

WriteMeansExample
{name} (single braces)A value the agent works out during the call/patients/{patient_id}
{{name}} (double braces)A value the call already knows (call data)/clinics/{{clinic_code}}

Each single-brace placeholder gets a row in a Path values card, where you describe what the agent should collect. Path values are always filled by the agent.

The host is fixed. You can't put a placeholder in the domain, and query parameters go in the Query card, not after a ? in the URL.

Step 5: Build the request

Below the endpoint, the request is split into three cards: Body, Headers and Query. A POST, PUT or PATCH shows Body first. A GET or DELETE shows Query first.

Click Add a field, Add a header or Add a query parameter to add a row. Each row has a name, a Type and a Filled by setting.

A custom HTTP tool open on the Setup tab in a VAW Native Pod, Builder view selected. The tool has a Name and Description filled in, a Bearer token connection chosen under Connection, Method POST and an Endpoint such as https://api.example.com/v1/patients/{patient_id}/notes. Below it, the Path values card shows patient_id, and the Body card shows two rows: 'note' (Text, Filled by 'Agent, during the call', Required ticked, with a description) and 'clinic_id' (Text, Filled by 'Set per agent'). The 'What the agent sees' panel is visible on the right. Blur the connection name if it names a real customer.

Where each value comes from

Filled byWhat happensAvailable in
Agent, during the callThe agent collects the value from the conversation. Write a short description of what to collect: it's how the agent decides.Body, Query
Same every timeYou type the value once and it's sent unchanged. Type {{ to insert call data instead.Body, Query, Headers
Set per agentEach agent supplies its own value when the tool is attached, such as a clinic ID.Body, Query, Headers
Each field separatelyFor an Object or List: you set each field inside it on its own.Body

Types are Text, Number, Whole number, True or false, Object and List. Headers and query parameters take single values only.

A few more controls:

  • Required: in the Body, tick this for agent-filled fields the agent must always supply.
  • Limit to a set of choices: for an agent-filled value, list the only values allowed, such as morning and afternoon. Type a choice, then press Enter.
  • Call data: in a Same every time value, type {{ to pick a name. The list groups names under Provided on every call (such as system.customer_number and system.call_id), Saved by another tool in this Pod and Used in an agent's instructions. You can also type a name of your own and pass it in when the call starts. See Use Call Data and Variables in Your Prompt.

Switch from Builder to Preview to see the request as it will be sent. Values the agent or call data will fill are shown in italics. The What the agent sees panel on the right lists exactly what the agent is asked for. The agent never sees the URL, the headers, your typed values, call data or the connection.

Step 6: Save the tool

Click Save changes. You'll see Tool created.

If agents already use the tool, you're asked to confirm first. Their next calls use the new version, and calls in progress finish with the current one. There's no version history: to undo a change, edit the tool and save again.

Next:

  1. Decide what the agent hears back on the Response tab.
  2. Check the write setting and timeout on the Safety tab.
  3. Send a real request from the Test tab.
  4. Attach the tool to an agent.

Troubleshooting

Tools only send over HTTPS. Change the URL to its https:// address. If the API only offers http://, it can't be used as a tool.

Remove everything from the ? onwards in the Endpoint. Add each parameter as a row in the Query card instead.

The domain can't contain a placeholder. Type the full domain and put placeholders after it, in the path.

A row has a problem with its name. The rows with a problem are marked in red, and their cards open automatically. Common causes:

  • A missing name. Every field, header and query parameter needs one: it's the key the API receives.
  • A duplicate name. Two rows in the same place share a name.
  • A header name with a space or other invalid character. Header names take letters, numbers, - or _, with no spaces.
  • An invalid per-agent name. The name shown on each agent for a Set per agent value can use letters, numbers, - and _, with no spaces, up to 64 characters.
  • An empty object. An Object needs at least one property inside it.

Tools can't call your own computer or a private network address. Use the API's public HTTPS address.

A value written as {{name}} had no value on that call, so the request wasn't sent. Make sure the call passes that call data in, or that the tool which saves it runs first. To see what happened, open the call in Call Logs and expand the tool's entry in the transcript.

Each agent that already uses the tool needs a value for the new field before it can run the tool again. Open the agent's Tools tab and fill it in. See Attach Tools to an Agent.