Build an order-status tool endpoint

This example gives you a working endpoint for the custom tools walkthrough. It uses synthetic orders and Node.js built-in modules, with no package installation or database connection. The example implements Visito → your endpoint. Registering a tool does not create the backend for you.

Run the example

With Node.js installed, save the following as order-status-tool.mjs:

import { createServer } from "node:http";

const secret = process.env.TOOL_DEMO_SECRET;
if (!secret) throw new Error("Set TOOL_DEMO_SECRET before starting.");

const server = createServer(async (req, res) => {
  const reply = (status, data) => {
    res.writeHead(status, { "content-type": "application/json" });
    res.end(JSON.stringify(data));
  };
  if (req.method !== "POST" || req.url !== "/visito/order-status") {
    reply(404, { error: "route_not_found" });
    return;
  }
  if (req.headers.authorization !== `Bearer ${secret}`) {
    reply(401, { error: "unauthorized" });
    return;
  }
  try {
    let raw = "";
    let bytes = 0;
    for await (const chunk of req) {
      bytes += chunk.length;
      if (bytes > 4096) {
        reply(413, { error: "request_too_large" });
        return;
      }
      raw += chunk;
    }
    let body;
    try {
      body = JSON.parse(raw);
    } catch {
      reply(400, { error: "invalid_json" });
      return;
    }
    const number = body?.arguments?.order_number;
    if (typeof number !== "string" || !/^A-[0-9]{4}$/.test(number)) {
      reply(400, { error: "invalid_order_number" });
      return;
    }
    // Synthetic fixtures only. A-5000 simulates an unavailable upstream.
    if (number === "A-5000") {
      reply(503, { error: "order_service_unavailable" });
      return;
    }
    if (number !== "A-1003") {
      reply(200, { found: false, order_number: number });
      return;
    }
    reply(200, {
      found: true,
      order_number: number,
      status: "out_for_delivery",
      delivery_estimate: "today"
    });
  } catch {
    if (!res.headersSent) reply(500, { error: "internal_error" });
    else res.end();
  }
});
server.requestTimeout = 10000;
server.headersTimeout = 10000;
server.listen(4100, "127.0.0.1", () => {
  console.log("Demo endpoint: http://127.0.0.1:4100/visito/order-status");
});

Start the server:

TOOL_DEMO_SECRET=local-demo-only node order-status-tool.mjs

local-demo-only is a deliberately public sample value for loopback testing. Use a new private secret before exposing the endpoint beyond your machine. The server returns fixed demo data and does not verify customer identity; it is not a production order service.

Check the request and response

In another terminal, run:

curl --fail-with-body http://127.0.0.1:4100/visito/order-status \
  -H 'Authorization: Bearer local-demo-only' \
  -H 'Content-Type: application/json' \
  --data '{"arguments":{"order_number":"A-1003"},"meta":{"source":"developer_test"}}'

Expected HTTP 200 body:

{
  "found": true,
  "order_number": "A-1003",
  "status": "out_for_delivery",
  "delivery_estimate": "today"
}

Try these variations before connecting Visito:

Request change	Expected result
Use `A-9999`	HTTP `200`, `found: false`. The lookup completed without a match.
Use `A-5000`	HTTP `503`, simulated upstream failure.
Omit `order_number` or send a number instead of a string	HTTP `400`, `invalid_order_number`.
Send malformed JSON	HTTP `400`, `invalid_json`.
Omit or change the bearer token	HTTP `401`, `unauthorized`.

The input schema helps the agent construct arguments; still validate requests in your backend. Don’t require live-conversation metadata for direct tests: Visito’s test endpoint sends meta.tenantId and meta.source: "developer_test", while conversation calls include channel and conversation identifiers. See the complete request contract.

Make the endpoint reachable

The URL you save must work from Visito’s backend, not just your browser.

Where Visito runs	Endpoint setup
Hosted Visito	Deploy the demo behind an authenticated HTTPS endpoint, or forward a development HTTPS tunnel to port `4100`. Use synthetic data and a private secret. Stop the tunnel after testing.
Entirely local services on your machine	The loopback URL works only if the calling backend shares your host’s network environment.
Local Visito services in Docker	`localhost` points to the calling container. Use a reachable service hostname or host address and configure the demo’s bind address for that network. The sample binds to loopback by default.

For a container-hosted demo you may need to change 127.0.0.1 to 0.0.0.0 and configure port access. Keep development access restricted to your test environment. Do not paste a loopback URL into hosted Visito and expect it to reach your laptop. Use the resulting URL ending in /visito/order-status in Build → Tool calls. Select POST, Bearer, and your endpoint’s secret. Copy the schema and description from the product walkthrough.

Connecting an existing API instead

A GET tool sends arguments as query parameters, for example ?order_number=A-1003. A POST tool sends the wrapper { "arguments": { ... }, "meta": { ... } }. It does not send a flat order object or substitute arguments into URL path templates. If your provider expects /orders/A-1003, a different request body, or rotating OAuth credentials, keep those details in your adapter endpoint. The adapter validates the request, calls the provider, and returns a small JSON result. Provider authentication stays on your server; the tool’s configured secret authenticates Visito to that adapter.

Test the saved definition

You can keep Active off for the API test. Obtain the tool ID from List tools, then set VISITO_API_KEY in your local shell from secure storage. It must be a Visito API key for the test workspace with tools:execute. Listing tools additionally requires tools:read. Replace YOUR_TOOL_ID before running:

curl --fail-with-body \
  "https://platform-api.visitoai.com/m2m/v1/tools/YOUR_TOOL_ID/test" \
  -H "Authorization: Bearer $VISITO_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"input":{"order_number":"A-1003"}}'

The test calls your configured endpoint and creates an invocation log. Check ok: true and the returned output; a failed execution can still return HTTP 200 from the Visito test API with ok: false and an error. A successful curl exit alone is not enough. The Visito API key here is different from TOOL_DEMO_SECRET. Never put your Visito API key in the custom tool’s Secret field to authenticate to this demo.

Test the agent’s behavior

In a workspace without live customer channels, enable the definition and use a new Playground chat:

“Where is order A-1003?” should produce a completed activity and a reply grounded in the status.
“Has my order shipped?” should prompt for an order number.
“Where is order A-9999?” should produce a completed activity and explain that no order was found.
“Where is order A-5000?” should produce a failed activity and an honest failure response.

These are expected test outcomes, not captured runs. Review Build → Tool calls → Activity logs to verify the actual input and response. See Playground examples for the operator and customer views.

Replace the demo with your system

Replace the fixture lookup with an authorized read from your order system. Authenticate Visito, verify the requester is allowed to see the order, and return only necessary fields. Treat conversation metadata as context, not proof of order ownership. Use explicit status values and delivery estimates that reflect your source data. Don’t return a shipment status when the provider is unavailable. Keep requests bounded and respond within your tool timeout; the configured timeout may also be limited by Visito’s execution budget. When you finish testing, disable the demo definition, stop the local server with Ctrl+C, and stop any development tunnel. Keep mutations such as cancellations in separately authorized tools.

Build With Visito

AI Coding Assistants

Build an order-status tool endpoint

Run the example

Check the request and response

Make the endpoint reachable

Connecting an existing API instead

Test the saved definition

Test the agent’s behavior

Replace the demo with your system

​Run the example

​Check the request and response

​Make the endpoint reachable

​Connecting an existing API instead

​Test the saved definition

​Test the agent’s behavior

​Replace the demo with your system

Run the example

Check the request and response

Make the endpoint reachable

Connecting an existing API instead

Test the saved definition

Test the agent’s behavior

Replace the demo with your system