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:

ts
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.title labels 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:

tsx
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, render returns 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 execute or render runs. 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() over z.number().
  • The model is held to a schema only when every object in it lists its properties and allows no other keys. A free-form object such as z.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.

tsx
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/core has defineTool only, because its widgets carry no render.
  • 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 execute callback after validation. Removing a tool or replacing its parameters schema blocks pending execution. Keep schema objects stable when updating only callbacks.
  • Widget renders re-read the current widgets prop, 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.

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.