Building a Custom HTTP Tool

Building a Custom HTTP Tool

Applies to: AGS 1.0  |  Level: Intermediate / technical  |  Reading time: 9 min
Part of: Using Tools with Your Agent (Overview)  |  Last reviewed: 25 Sep 2026

This guide shows you how to build your own tool for an in-house system, a vendor that isn't in the Tool Catalog, or your own workflow or API. If your system is already listed, use Installing a Vendor Tool instead. It's faster and needs no technical setup.

What you'll be able to do

  • Name and describe a tool so the agent calls it at the right moment
  • Store the endpoint's credentials securely
  • Define parameters the agent fills in, and ones it never has to think about
  • Set the request, timeout and caching behavior
  • Save and test the tool before any caller reaches it

Before you begin

You need these three things. If you're missing any of them, get them from your technical contact before you start.

  • The endpoint URL and HTTP method.
  • The authentication details the endpoint expects.
  • An example request that already works, for example from Postman or cURL.

For the full checklist, see Before you begin in the overview.

How the builder is laid out

The builder has five sections listed down the left under Configuration: Identity, Authentication, Request, Parameters and Behavior. A Test panel stays on the right throughout.

✔ Why the steps skip ahead: this guide sets up Parameters before Request, even though the builder lists them the other way round. The request's headers and body are built from your parameters, so it's easier to define them first.

Steps

Step 1: Open the builder

In Tool Catalog, find Custom HTTP Tool ("hand-build a tool against any HTTP endpoint") and click Build.


Step 2: Identity – name and describe the tool

  • Tool name: short, lowercase, and reads like an action, for example get_customer_by_email, create_ticket, check_availability. Letters, numbers, dashes and underscores only, 50 characters maximum.
  • Description: one or two sentences that answer "When should the agent reach for this?" Write it as an instruction to the agent, not a definition.
⚠ The description is the most important field on the form. The agent reads it to decide when to call the tool. A vague description means the tool gets called at the wrong time, or not at all.
Weak descriptionStrong description
"Ticket tool.""Use when the caller reports a problem that cannot be resolved on the call. Creates a ticket and returns the ticket number."
"Calendar integration.""Use when the caller asks about availability or wants to book. Returns open slots for the next 14 days."
"Looks up stuff in the CRM.""Use at the start of a call to check whether the caller is an existing customer, using their phone number."




Step 3: Authentication

Open Authentication and enter the credentials the endpoint expects.

⛔ Keep secrets out of headers. Always enter API keys and tokens here, never as a hand-typed header in Request or Parameters. Credentials entered here are stored once and never shown in the tool definition.

Step 4: Parameters

Parameters are the pieces of information sent with the request. For each one, set:

  • Field name and type
  • Location: Body, Query, Path or Header
  • Required or optional
  • Description: tells the agent how to fill in the value

Each parameter belongs to one of three groups. Putting a value in the right group is what makes the call feel smooth.

GroupWho supplies the valueUse it for
DynamicThe agent, during the call. It asks the caller if it doesn't already know.Ticket ID, email address, description of the problem
StaticYou, once. The same value is sent with every request.Tenant or baseUrl, API version, a fixed queue or source ID
AutomaticAGS, injected for you (call ID, history and similar).Linking the request to the call record



⚠ Keep required Dynamic fields to a minimum. Every required Dynamic parameter is one more question the agent must ask before it can act. Three is a smooth call; seven is an interrogation. If a value never changes, make it Static so the agent never has to ask for it, and can never get it wrong.
Schema tips (technical readers)
  • Use enums wherever the set of values is closed. This stops the agent inventing values.
  • Spelled-out values such as names, emails and reference numbers need a format instruction in the description, for example: "Email address, lowercase, no spaces. Confirm spelling with the caller before submitting."
  • Dates: require an absolute YYYY-MM-DD. Resolve relative phrases like "next Tuesday" in the prompt, with the current date provided in the system prompt. Relative dates without that are a common cause of off-by-one-week errors.
  • Keep the response small. Everything the endpoint returns becomes context the agent has to read before it speaks.

Step 5: Request

Open Request and set the Method and URL. That's all this section holds. Headers and body are assembled automatically from each parameter's location in Step 4.

✔ Value missing from the request? Fix it in Parameters, not here.[



Step 6: Behavior

Behavior controls what happens around the HTTP call itself.

SettingWhat it does and how to set it
Timeout (seconds)How long AGS waits for a response before giving up. Default is 5. On a live call, anything above about 8–10 seconds is dead air, so speed up the endpoint rather than raising this.
Default reactionWhat the agent does while the call runs. Leave it at Default unless you have a specific reason to change it.
PrecomputableOff by default. Turn it on only for pure lookups that return the same result every time, so AGS can cache the result.
Static ResponseOff by default. Skips the HTTP call and returns a fixed payload. Useful as a stand-in while you shape a prompt.
⛔ Never turn on Precomputable for a tool that creates or changes a record. A cached result means the record may not be created. Turn Static Response off before going live, or the tool will never reach the real system.



Step 7: Save, then test

⚠ Save first. The Test panel stays inactive on a new tool until you save it. Most people expect to test first, so this catches them out.
  1. Click Save in the top-right corner.
  2. In the Test panel, enter sample values for any Dynamic parameters.
  3. Click Run test.
  4. Open Details to see the request that was sent and the raw response.
  5. Check that the response comes back in the shape you expect before going any further.
⛔ Tests write to the real system. The test uses your stored credentials but doesn't create a call session, so you can run it as often as you like. It still creates or changes real records, so point it at a sandbox or a throwaway record.

Verify it worked

Open the Installed Tools tab. Your custom tool should appear alongside your vendor tools.

⛔ Not live yet: saving a tool doesn't give it to any agent. Callers won't be affected until you attach it and deploy the change.

Next step

Continue with Attaching Tools to Your Agent & Writing Instructions to give this tool to an agent and tell it when to use it.