Browse docs
On this page
Tools and widgets
Tools let an agent call your application code. Widgets render your components in its replies. Follow the Todos tutorial for a working integration with shared state, a test prompt, and two-way updates.
Tools
Register an action in the chat's tools prop. This fragment assumes your application provides restartService:
tools: {
restart_service: {
metadata: { title: "Restart a service" },
description: "Restart one of the host app's services by name",
parameters: { type: "object", properties: { service: { type: "string" } }, required: ["service"] },
execute: async ({ service }) => await restartService(String(service)),
},
}- The resolved value is returned to the agent as the tool result. A thrown error leaves the action's outcome unknown, because it may already have changed external state.
- Return JSON-compatible values. Omit absent object fields instead of setting them to
undefined, and convert dates or custom objects to plain values. - The SDK names the tool when its result cannot be sent. Its action may already have happened, so read current state before retrying.
- A string
metadata.titlelabels the tool's transcript entry in prose instead of its registry name. - New tools reach the agent on its next run.
Widgets
Register a component in widgets. Your application provides StatusCard:
widgets: {
systemStatus: {
description: "Shows the current status of the host app's systems",
parameters: { type: "object", properties: { degraded: { type: "boolean" } } },
render: ({ degraded }) => <StatusCard degraded={Boolean(degraded)} />,
},
}- In React,
renderreturns JSX. Elsewhere it draws into a container and may return a cleanup. - Renders live in your app's tree, so state, context, and event handlers keep working. An inline picker can call the same mutation function as a form elsewhere in your app.
- Clicking a widget does not send a chat message or return a tool result. Have the agent read current state before its next change so it sees edits made through your UI.
- Reopening saved history restores widget props without rerunning business tools. Persist the host records those props reference, and render a fallback when a record was deleted.
Schemas
parameters is a plain JSON Schema object, or any Standard Schema validator such as Zod, Valibot, or ArkType.
- A Standard Schema is enforced in the browser before your
executeorrenderruns. JSON Schema export errors are surfaced during declaration. - With plain JSON Schema, nothing validates in the browser: treat the agent's input as untrusted.
- Models sometimes send numbers as strings. With Zod, prefer
z.coerce.number()overz.number(). - The model is held to a schema only when every object in it lists its
propertiesand allows no other keys. A free-form object such asz.record(), or a validator that cannot export JSON Schema, still works, but the model may then send input that does not match.
Typed definitions
defineTool and defineWidget infer callback inputs from a Standard Schema. They return the definition unchanged.
import { defineTool, defineWidget } from "@astralbeam/sdk/react"
import { z } from "zod"
const todoCard = defineWidget({
description: "A single todo from the host app, addressed by its id",
parameters: z.object({ id: z.coerce.number() }),
render: ({ id }) => <TodoCard id={id} />,
})
const createTodo = defineTool({
description: "Create a new todo and append it to the list",
parameters: z.object({ text: z.string().min(1) }),
execute: ({ text }) => addTodo(text), // text: string, validated before this runs
})- Import them from
@astralbeam/sdk/react(JSX widgets) or@astralbeam/sdk/client(container widgets).@astralbeam/sdk/corehasdefineToolonly, because its widgets carry norender. - With plain JSON Schema, callback input is
Record<string, unknown>. Validate it before use.
Live state
Tools can run many turns after registration. Read current state when they execute.
- All session adapters resolve the current
executecallback after validation. Removing a tool or replacing itsparametersschema blocks pending execution. Keep schema objects stable when updating only callbacks. - Widget renders re-read the current
widgetsprop, so host state changes re-render projected UI. - Pass ids in widget props and resolve them against your own state, rather than snapshotting data into props.
Read after a write
An agent can call several tools before React renders again. Commit each change before returning its result so the next tool reads it.
- For server data, await the mutation and read from the authoritative response or refreshed cache.
- For browser data, commit to a synchronous store before returning. React can subscribe to that store with
useSyncExternalStore. - Resolve issue, project, and assignee IDs inside the active Tenant. A valid schema does not establish ownership.
- Keep manual edits and agent edits on the same mutation path so both validate, persist, and notify the UI in the same way.
Linearity’s store demonstrates this with localStorage. Its issue widgets receive only an ID and resolve the latest issue on each render.
Navigating the host app
Register navigation as a host tool. Look up destinations from your app's records, validate them, and pass them to your client router. Keep the sidebar in a persistent layout so navigation preserves the conversation.
Linearity’s navigation tool accepts only known views and records in the active workspace. It rejects external URLs and another workspace’s IDs. Your production app must also enforce the current user’s permissions, just as it does for manual navigation.