Open Markdown · Agent index

Connect the assistant to your business tools

A client tool lets the assistant call a function in the customer's browser. That function can call your existing authenticated backend to look up an order, check availability or perform an authorized business action.

Keep business access on your server

The flow is: customer conversation → browser tool → your authenticated server route → existing service client. Your server derives customer/tenant identity, validates inputs and decides what the customer may access. Tool arguments and model output are untrusted input, not proof of ownership.

Client tools run only during a live browser session. They do not create a native provider integration, an unattended job, or a tool for voice/SMS/email agents.

Example: order lookup

This browser-side example expects your application to implement GET /api/support/orders/:id. That is your route, not a Masheev endpoint.

import { init, type ClientToolDefinition } from "@masheev/embed-sdk/js";

const lookupOrder: ClientToolDefinition = {
  name: "lookup_order",
  description: "Look up delivery status for an order owned by the signed-in customer.",
  parameters: {
    type: "object",
    properties: { orderId: { type: "string", description: "The order reference" } },
    required: ["orderId"],
  },
  execute: async (args) => {
    if (typeof args.orderId !== "string" || !args.orderId.trim()) {
      return { success: false, error: "Provide an order reference." };
    }
    try {
      const response = await fetch(`/api/support/orders/${encodeURIComponent(args.orderId)}`, {
        credentials: "same-origin",
        signal: AbortSignal.timeout(10_000),
      });
      if (!response.ok) return { success: false, error: "The order could not be retrieved." };
      const order = await response.json();
      return { success: true, data: { status: order.status, deliveryDate: order.deliveryDate } };
    } catch {
      return { success: false, error: "Order lookup is temporarily unavailable." };
    }
  },
};

init({ inboxId: "YOUR_INBOX_ID", tools: [lookupOrder] });

Mount once in the application's browser lifecycle. A React application can supply the same tools in useMasheev configuration. Keep definitions stable between renders.

Backend contract

Implement the route with the application's existing authentication. Look up the order within the authenticated customer's tenant/account, not globally and then trust a browser-supplied owner ID. Return only the fields the assistant needs. Validate provider responses, cap request duration, and avoid logging sensitive payloads.

For write actions, enforce authorization and CSRF protection as appropriate to the existing app, use a stable operation/idempotency key, and preserve business confirmation. The SDK's needsApproval option can request user approval, but it does not replace server permission checks.

Verification

Test a successful lookup, another customer's order, a logged-out request, a provider timeout, and an invalid argument. For mutations, test confirmation and repeated requests. Verify the model receives a clear success or failure result and does not claim an action succeeded when the backend rejected it.

For multi-step browser journeys, see conversation workflows.