Skip to main content
The whole flow happens inside the dashboard — no CLI, no deploys on our end, no support ticket.

​
Prerequisites

  • Power Tools add-on is active on your account (Account → Billing → Add-ons → Power Tools).
  • An HTTPS endpoint somewhere (real backend, ngrok tunnel, Cloudflare tunnel — anything reachable on the public internet over TLS).
  • A super-admin or admin role on the tenant so the dashboard exposes the tool manager.
Building locally? Expose your local server through a tunnel:
ngrok http 3000
# → https://abc-123.ngrok-free.app
Use the tunnel URL as your endpoint. Switch to your real URL when you deploy.

​
1. Open the tool manager

In the dashboard:
  1. Open Agent Studio.
  2. Pick the agent that should have the new tool.
  3. Open the Tools tab.
  4. Find the Custom HTTP Tools card under Power Tools and click Manage.
You’ll land in a dialog. First time through, it’s empty.

​
2. Pick a starting point

Two paths:
Pre-fills a lookup_routing tool that takes a query string. Good if you’re new to JSON Schema or just want to see what a working tool looks like before customizing.

​
3. Configure

Fill in (or edit) these fields:
​
Name
string
required
Lowercase, snake_case identifier, 3-64 characters. This is what the AI sees as the function name when deciding whether to call your tool. Examples: lookup_routing, check_balance, fetch_order_status.Reserved names (built-in tools like transfer_to_pbx, end_call, etc.) are blocked.
​
Description
string
required
10-500 characters. The AI uses this verbatim to decide when to call your tool. Write it like a one-paragraph briefing for a new colleague: what does this tool answer, and when should the AI reach for it?Bad: Looks up routing.Good: Ask our backend which PBX extension should take the caller. Pass the caller's intent (e.g. "billing", "sales", "after-hours emergency") as 'query'. Returns an extension number and a one-line hint.
​
URL
string
required
Full https://... endpoint. We validate live as you type:
  • Must be https:// (no http://)
  • No credentials in the URL (https://user:pass@...) — use the auth field below
  • No private IPs (10.x, 192.168.x, localhost, AWS metadata, etc.)
  • No links into our own infrastructure (*.getsmartalex.com, *.supabase.co, *.amazonaws.com)
  • Max 2048 characters
See Security restrictions for the full ruleset.
​
Parameters
JSON Schema
required
A standard JSON Schema describing what arguments the AI passes. The dashboard editor validates as you type and shows a live preview of what the AI will see.Minimal example:
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "What the caller wants in plain English"
    }
  },
  "required": ["query"]
}
If you have an example arguments object, hit Generate from example to scaffold a schema automatically.
​
Authentication
enum
Pick one:
  • Bearer token — we send Authorization: Bearer <your-token>. Most common.
  • Custom header — we send <Header-Name>: <your-token>. Useful when your API expects X-API-Key or similar.
  • None — no auth header. Sign-only (our HMAC signature is still sent).
Tokens are stored encrypted in Vault. The dashboard never displays them after save.
​
Active
boolean
Toggle off if you want to keep the configuration but stop the AI from calling the tool.

​
4. Save and save the signing secret

The first time you save any HTTP Tool on this tenant, the dashboard generates a per-tenant signing secret and shows it in a modal.
This is the only time we display the signing secret. Copy it into your environment / secrets store before clicking “I’ve saved it”. If you lose it, rotate (which invalidates the old secret immediately) and update your endpoint with the new one.
The secret has the prefix shs_ and is 64 hex characters (32 bytes / 256 bits). You’ll use it on your endpoint to verify every request — see Signature verification.

​
5. Test fire

Hop to the Test tab of the tool you just configured:
  1. The form pre-fills sample arguments matching your schema.
  2. Click Send test.
  3. You’ll see the full request — URL, headers (including the live HMAC signature), body — and your endpoint’s response, status code, and latency.
  4. Click Copy as curl to replay the exact same call from your terminal. Useful for verifying signature math on your side.
If anything fails, the result panel shows the exact error code with a one-line explanation. Cross-reference with Error codes.

​
6. Verify the AI can see it

Back in Agent Studio, the Custom HTTP Tools card should now show “Active” with a count of 1 configured. The agent automatically picks up the descriptor on the next call — no redeploy. Place a test call and ask something that should trigger your tool. The dashboard’s Invocations panel will show the live request 1-2 seconds after the call ends, with full payload, response, latency, and the signature we sent.

​
7. Done

That’s the whole flow. From here:
  • Add more tools (different names, same signing secret).
  • Tweak descriptions to nudge the AI toward calling your tool in different scenarios.
  • Watch the invocations panel for failures and click into any row to see the full request / response and a “Replay as curl” button.

Next: Request & response shape

Exact body, headers, and what you should return.