Custom tools

Custom agent tools

Let the agent call your HTTP webhook as a tool mid-conversation: look up an order, find a record, create a ticket, hit your system. You describe the tool (name, parameters, URL), the agent decides when to call it — the platform sends the request to your server and returns the response back into the dialog.

Available on the Business and Pro plans. Configured in the dashboard, in the project editor.

How to set it up

  1. Open a project → “Agent” tab → “Custom tools” block.
  2. Click “Add tool” and fill in:
    • Name — Latin, like a function name (get_order_status). The model calls the tool by this name.
    • Description — when and why to call it. The more precise, the better the agent’s timing.
    • Parameters — a list of arguments: name, type (string/number/integer/boolean), description, required flag. The agent extracts their values from the conversation.
    • Method and URL — POST (default) or GET, and your webhook address (https://…).
  3. Save the project.

How it works

When the agent decides a tool is needed, the platform sends a request to your URL with the arguments, waits for the response, and passes it to the agent as the tool result — the agent continues the conversation with that data.

Request (for POST — JSON body; for GET — the same fields as query params):

POST https://your-backend.com/order-status
Content-Type: application/json
 
{ "order_id": "A-2045" }

Response — any text or JSON (200 OK). The agent receives it:

{ "status": "in transit", "eta": "tomorrow by 6pm" }

The agent voices the meaning: “Your order is in transit, arriving tomorrow by 6pm.”

Limits and behavior

ParameterValue
Tools per projectup to 10
Request timeout~8 seconds (voice can’t wait long)
Response size in contextup to ~1500 chars (longer is truncated)
MethodsGET, POST
Ports80, 443

If the webhook times out or errors, the agent gets a short “couldn’t run it” and keeps the conversation going instead of breaking.

Security

⚠️

The webhook response is data, not commands. The agent is instructed not to follow instructions found in the response body (prompt-injection protection). Don’t return “directives” to the agent.

  • The URL must be a public https endpoint. Requests to loopback, private, and special addresses (127.0.0.1, 10.0.0.0/8, 192.168.…, 169.254.169.254, etc.) are blocked — SSRF protection; the address is validated and pinned at connect time, so DNS rebinding won’t work.
  • For authentication, add your own header (e.g. Authorization: Bearer …) in the tool config. The Host header cannot be overridden.
  • Verify on your side that the request really came from you (a secret in a header/path).

Model compatibility

Tools are called natively on models with structured tool-calls (e.g. Gemini). On YandexGPT the call “leaks as text” — the platform detects and executes it automatically, so custom tools work there too.

WebhooksKnowledge base