Browse docs
On this page
Todos tutorial
Build an assistant that adds, updates, and deletes todos, with live cards in chat. You'll connect tools to the same state and components the app already uses. The code excerpts link to complete files on main.
1. Run the starter
You'll need Git, Bun, and a model-provider API key. The starter branch includes a working todo list with browser persistence and a TodoCard component. Create a working branch from it in a clean checkout:
git fetch origin
git switch -c todos-tutorial origin/examples/todos-starterComplete contributor setup to install dependencies, seed development data, and build the SDK. Then run Platform and Todos in separate terminals:
bun run --cwd platform devbun run --cwd examples/todos devOpen localhost:4700. Add a todo, toggle it, and reload to check persistence.
2. Connect authentication
Install the built workspace SDK from the repository root:
bun add --cwd examples/todos '@astralbeam/sdk@workspace:*'Setup writes examples/todos/.env if absent. Check its Todos API key, agent ID, and API URL. The key and agent must belong to the same organization. Keep the key server-side.
Copy the demo token route, server config, and demo identity. The route's core is:
const token = await createAstralBeamToken({
apiKey: API_KEY,
user: DEMO_CHAT_USER,
tenant: DEMO_CHAT_TENANT,
})
return tokenResponse({ token }, 200)The SDK calls /api/astralbeam/token by default. Restart Todos after changing environment values.
NOTE: The demo grants one fixed identity and is disabled in production. In your app, derive user and tenant IDs from an authenticated session. See Authentication.
3. Register host tools
Create TodosAssistant. Its tools call the starter's useTodos helpers, just like the native list. For example, create_todo needs only its input schema and the existing mutation:
const { createTodo } = useTodos()
const tools: Record<string, ToolDefinition> = {
create_todo: {
metadata: { title: "Create a todo" },
description: "Create a new todo and append it to the list.",
parameters: {
type: "object",
properties: { text: { type: "string" }, completed: { type: "boolean" } },
required: ["text"],
},
execute: (input) => ({ created: createTodo(input) }),
},
}Use the same pattern for get_todos, update_todo, and delete_todo from the complete tool definitions. getTodos() reads current state at execution time, so consecutive calls see earlier edits. Mutations validate model input before changing the list.
4. Show live cards
Register todoCard in the assistant's widgets prop with an id number parameter. Reuse the starter's TodoCard and look up that ID in reactive todos:
render: ({ id }) => {
const todo = todos.find((entry) => entry.id === Number(id))
return todo && <TodoCard todo={todo} onToggle={() => toggleTodo(todo.id)} />
},The card and list now share state in both directions. Pass record IDs through the conversation, and authorize any backend mutations on your server. See the complete widget registration.
5. Mount the assistant
Copy the public configuration from config.ts. Inside TodosAssistant, pass the API URL, agent ID, and registrations to the SDK:
<AstralBeamChat
apiUrl={ASTRALBEAM_API_URL}
agentId={CHAT_AGENT_ID}
tools={tools}
widgets={widgets}
sandboxPanel
/>Use the complete component for imports and sidebar sizing. Add the sidebar rules from styles.css.
Import TodosAssistant into AppShell and place it immediately after </main>. The shared layout keeps chat mounted during navigation:
<TodosAssistant colorScheme={colorScheme} />6. Try it
In Platform, configure a provider under Models and assign its model to the Todos agent under Agents. Setup does this when OPENAI_API_KEY is configured and the organization has no provider. The seed installs the Todos agent prompt. Model calls may incur charges.
- Ask "Add a todo called Water the plants and show its card." Check that a row and card appear.
- Toggle the card, then toggle the row. Both should stay in sync.
- Ask "Delete Water the plants." Reload and check that it stays deleted.
You now have tools and widgets connected to the same todo list.
Try files and code execution
To extend the example, enable Allow file attachments on the agent, configure Platform file storage, and select a tested sandbox provider. Attach samples/tasks.csv and ask "Add the tasks from this CSV." Check the new rows.
Ask "Export my todos as CSV using the sandbox." Check the command exit codes and download the result from Sandbox. Published files remain in saved history after the workspace stops.
Continue
Compare your app with the completed example. To add a customer user list, follow Tenant directories. For automated checks, use the example's browser suite, whose agent tests spend provider credits.
Read the security model before connecting tools to production data.