Client-side tools

What a client-side tool is

A client-side tool is a function on your page that the agent can call. You give it a name, a description, and a JSON Schema for its input. When the agent uses it, the SDK runs your function and returns the result to the agent, which continues its answer. Use tools to read app state (the cart, the user’s plan), act in the browser (navigate, open a panel, fill a form), or call your own APIs with the visitor’s session.

Register a tool

const chatbot = tai.getInstance("YOUR_ASSISTANT_ID");

chatbot.registerTool({
  name: "getOrderStatus",
  description: "Returns the shipping status of one of the customer's orders.",
  parameters: {
    type: "object",
    properties: {
      orderId: { type: "string", description: "The order number shown in the customer's account." },
    },
    required: ["orderId"],
  },
  execute: async ({ orderId }) => {
    const response = await fetch(`/api/orders/${orderId}/status`);
    if (!response.ok) return { error: `Order ${orderId} not found` };
    return response.json();
  },
});

string

required

The tool name the agent calls. Use letters, digits, and underscores. Leading and trailing spaces are trimmed.

string

required

Tells the agent when to use the tool. Write it for the model: what the tool does, what it returns, when not to use it.

object

required

A JSON Schema object describing the input. Start with type: "object" and list fields under properties. This object is passed to the model as the tool’s input schema without changes, so a bare map of field names is not valid.

function

required

Receives the input the agent produced, matching your schema. May return a value or a Promise. The return value is JSON-serialized and given to the agent.

string

Shown in the chat while the tool runs. Defaults to name.

A tool with no input still needs a schema:

parameters: { type: "object", properties: {} }

registerTool() throws if name, description, or execute is missing or execute is not a function.

When tools reach the agent

You can register tools before or after the agent is ready. The SDK sends the full tool list to the iframe when the agent becomes ready and again on every registerTool() or unregisterTool() call. The iframe includes the current list with every request, so a tool registered between two messages is available for the second one. The agent only sees the name, display name, description, and schema. Your execute function stays on your page.

Execution rules

Each call has 30 seconds. If execute has not settled by then, the agent receives no result and continues without it.
A thrown error or rejected Promise is returned to the agent as { error: "Error executing tool: <message>" }. Return an { error } object yourself when you want to control the wording.
A call for a tool name that is no longer registered returns { error: 'Tool "<name>" not found' }.
Return plain data. Functions, DOM nodes, and circular structures do not serialize.
Tool calls happen while the assistant is thinking or answering, so sendMessage() returns busy until the answer that triggered the tool completes.

Remove or list tools

chatbot.unregisterTool("getOrderStatus"); // returns true if it existed
chatbot.getRegisteredTools();             // ClientTool[]

window.addEventListener("teamAIChatbotReady", () => {
  const chatbot = tai.getInstance("YOUR_ASSISTANT_ID");

  chatbot.registerTool({
    name: "getCart",
    description: "Returns the items and total currently in the visitor's shopping cart.",
    parameters: { type: "object", properties: {} },
    execute: () => window.app.cart.snapshot(),
  });

  chatbot.registerTool({
    name: "openPage",
    displayName: "Opening page",
    description: "Navigates the visitor to a page on this site. Use only paths that start with /.",
    parameters: {
      type: "object",
      properties: {
        path: { type: "string", description: "Site-relative path such as /pricing" },
      },
      required: ["path"],
    },
    execute: ({ path }) => {
      if (!path.startsWith("/")) return { error: "Only site-relative paths are allowed" };
      window.location.assign(path);
      return { navigated: path };
    },
  });
});

Validate every input inside execute. The schema guides the model but does not guarantee the values it sends.

Tell the agent the tools exist

The agent sees the tool descriptions on every request, so it can use them without further prompting. For tools the agent should prefer, or should ask before using, add a line to the agent’s instructions in TeamAI, for example “Use getCart before answering questions about prices or totals.”

Embed SDK

What a client-side tool is

Register a tool

When tools reach the agent

Execution rules

Remove or list tools

Example: navigation and app state

Tell the agent the tools exist

​What a client-side tool is

​Register a tool

​When tools reach the agent

​Execution rules

​Remove or list tools

​Example: navigation and app state

​Tell the agent the tools exist

What a client-side tool is

Register a tool

When tools reach the agent

Execution rules

Remove or list tools

Example: navigation and app state

Tell the agent the tools exist