Skip to Content
Baseera Docs

Tools and approvals

Define tools the assistant can call, show approval cards, and let users undo a change.

A tool is a function in your app that the assistant can call. The tool runs in the browser, with your component's data and handlers. The Baseera runtime never stores or runs your tools: it receives the tool specs with every turn and streams the model's calls back.

Define a tool

components/invoice-tools.tsx
"use client";
import { useBaseeraTool } from "@baseera/react";
import { z } from "zod";

const getInvoiceInput = z.object({ number: z.string() });
const markPaidInput = z.object({ number: z.string(), paidOn: z.string().date() });

export function InvoiceTools({ api }: { api: InvoiceApi }) {
  // read: runs at once
  useBaseeraTool({
    name: "getInvoice",
    description: "Get an invoice by its number",
    kind: "read",
    input: getInvoiceInput,
    run: ({ number }) => api.getInvoice(number),
  });

  // write: waits for the user's approval
  useBaseeraTool({
    name: "markInvoicePaid",
    description: "Mark an invoice as paid",
    kind: "write",
    input: markPaidInput,
    describe: ({ number, paidOn }) => `Mark invoice ${number} as paid on ${paidOn}`,
    run: async ({ number, paidOn }) => {
      await api.markPaid(number, paidOn);
      return { ok: true };
    },
    undo: async ({ number }) => {
      await api.markUnpaid(number);
    },
  });

  return null;
}

Define the Zod schema outside the component, or memoize it, so it keeps its identity.

Options

Prop

Type

A bad name, description or schema throws when the component renders.

The three kinds

KindUse it forWaits for approval
readLooking something up.No
draftAI content that a person still has to sign, such as a drafted email.Yes
writeChanging your data.Yes

Write a describe for every draft and write tool, so the user sees in plain words what will happen. Without it the card shows the tool name and its input as JSON, cut at 300 characters.

How a call flows

  1. The model calls a tool. The SDK checks the input against your Zod schema before run and before asking for approval. If it is invalid, run is not called and the model gets a short error listing what is wrong, so it can correct itself.
  2. A read tool runs at once. A draft or write tool waits in pendingApprovals with status awaiting_approval.
  3. The user approves or rejects. Every decision is reported to the runtime for the trace.
  4. Once every call in the turn is decided, approved tools run in call order. A result for an approved call carries approved: true, even if the tool then failed.
  5. A rejection goes back to the model as The user declined: reason.

A tool is registered while its component is mounted. The latest run and describe are used, so re-renders do not re-register. Changing name, kind, description or the schema does. Registering a name twice logs a console warning, and the latest registration wins until it unmounts.

Show approval cards

BaseeraSurface shows approval cards inside the conversation. To place them yourself, use BaseeraApprovals from @baseera/ui/connected:

import { BaseeraApprovals, BaseeraToolActivity } from "@baseera/ui/connected";

<BaseeraApprovals locale="en" />

It shows every draft and write call of the latest assistant message as a card in call order, with "1 of 3". Cards stay after the decision, showing Done, Rejected or Failed, and Undo when the tool provides it. Props: locale, digits, labels, dir, getValues, autoFocus, className and message.

ApprovalCard

ApprovalCard is the plain component behind it: props only, labels passed in.

import { ApprovalCard, getApprovalLabels } from "@baseera/ui";

<ApprovalCard
  description="Send invoice INV-1042"
  kind="write"
  state="pending"
  labels={getApprovalLabels("en")}
  values={[{ label: "Amount", value: "120 USD" }]}
  onApprove={() => {}}
  onReject={(reason) => {}}
  onUndo={() => {}}
/>

Its states are pending, running, done, rejected and failed. See Components for every prop.

Tool status lines

BaseeraToolActivity shows a status line for each read call of a message: "Checking invoices" while it runs, then done, failed, rejected or timed out. Pass friendlier phrases with toolLabels or describeActivity.

import { BaseeraToolActivity } from "@baseera/ui/connected";

<BaseeraToolActivity message={message} toolLabels={{ getInvoice: "Looking up the invoice" }} />

ToolStatus is the plain component: name, label, state (running, done, failed, rejected, timed_out), error, labels and dir.

import { ToolStatus, getToolStatusLabels } from "@baseera/ui";

<ToolStatus name="list_invoices" state="running" labels={getToolStatusLabels("en")} />

The built-in knowledge.search tool runs on the server. The SDK only displays it, with its own wording.

Undo

A draft or write tool can take undo. Once a call of that tool is done, the call has undoable: true, and undo(callId) from useBaseeraChat runs the tool's undo with the validated input and what run returned. Afterwards the call has undone: true.

  • The input and output are kept in memory only, never in chat state or storage, for the life of the page. They are dropped on reset(). After a reload, earlier calls are no longer undoable.
  • The model is not told about an undo, so its next turn does not know the change was reversed.
  • undo never throws to your UI. If the tool's undo fails, the call stays undoable so the user can try again. Handle and show your own errors inside undo.
  • Only calls that finished done are undoable, and only for tools that provide undo.

Build your own approval interface

import { useBaseeraApprovals } from "@baseera/react";

export function ApprovalBar() {
  const { pending, approve, reject, approveAll, rejectAll } = useBaseeraApprovals();
  if (pending.length === 0) return null;
  return (
    <section role="group" aria-label="Approval needed">
      {pending.map((a, i) => (
        <div key={a.callId}>
          <small>{i + 1} of {pending.length}</small>
          <p>{a.description}</p>
          <button onClick={() => approve(a.callId)}>Approve</button>
          <button onClick={() => reject(a.callId, "Not now")}>Reject</button>
        </div>
      ))}
      {pending.length > 1 && (
        <>
          <button onClick={approveAll}>Approve all</button>
          <button onClick={() => rejectAll()}>Reject all</button>
        </>
      )}
    </section>
  );
}

A call leaves pending as soon as you decide it, so "i of n" counts what is still open.

Inline approval

A custom tool that asks the user inside your own UI, such as a field's draft, can set inlineApproval: true on its definition (with useBaseeraToolDefinition). It runs at once with status awaiting_approval instead of showing a card. It gets { signal } as a second argument, which is aborted when the turn is stopped, and it throws BaseeraRejection(reason?) when the user declines. The model then gets { rejected: true, reason }.

import { BaseeraRejection, useBaseeraToolDefinition } from "@baseera/react";

useBaseeraToolDefinition({
  spec: { name: "suggestTitle", description: "Suggest a title", kind: "draft", inputSchema: { type: "object" } },
  inlineApproval: true,
  run: async (input, context) => {
    const decision = await askUserInPage(input, context?.signal);
    if (!decision.approved) throw new BaseeraRejection(decision.reason);
    return { approved: true };
  },
});

Next steps

On this page