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
"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
| Kind | Use it for | Waits for approval |
|---|---|---|
read | Looking something up. | No |
draft | AI content that a person still has to sign, such as a drafted email. | Yes |
write | Changing 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
- The model calls a tool. The SDK checks the input against your Zod schema before
runand before asking for approval. If it is invalid,runis not called and the model gets a short error listing what is wrong, so it can correct itself. - A
readtool runs at once. Adraftorwritetool waits inpendingApprovalswith statusawaiting_approval. - The user approves or rejects. Every decision is reported to the runtime for the trace.
- 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. - 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.
undonever throws to your UI. If the tool'sundofails, the call staysundoableso the user can try again. Handle and show your own errors insideundo.- Only calls that finished
doneare undoable, and only for tools that provideundo.
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 };
},
});