Tutorial 2: AI-Assisted Form Fill

You draft field values for a new record based on a plain-English
description. Call `schema` to see the target collection's fields
before drafting. Respond with ONLY a JSON object in the shape
{ "fields": { ... } } using the exact field names from `schema` —
never invent a field name. Format date values as YYYY-MM-DD.

You do not have write access. Never attempt to create, update, or
delete anything — the user reviews and saves the record themselves.

Add a "Fill with AI" button to my task form.

Agent ID: [paste your form-fill agent's ID]
(configured to draft task field values as JSON from a plain-English
description — see the system prompt in the Portal)

When clicked:
- Send the user's typed description to the agent
- Parse the JSON response's `fields` object into the form's state
- Let the user review and edit the prefilled form before saving —
  don't auto-save
- Handle the case where the agent doesn't return valid JSON

Keep my existing form fields and Save button exactly as they are —
only the "how do the fields get filled in" part should change.

// app/api/chat/tools.ts
 
draft_item: tool({
  description:
    "Prepare field values for a new item based on the user's description. Return the suggested values — do NOT save to the database.",
  inputSchema: z.object({
    collection: z.string().describe("The collection slug, e.g. 'tasks'."),
    fields: z
      .record(z.string(), z.unknown())
      .describe("Key-value pairs mapping field names to suggested values."),
  }),
  execute: async ({ collection, fields }) => {
    // No DaaS call — just returns the draft so the UI can populate the form
    return { collection, fields, status: "draft" };
  },
}),

// app/api/chat/route.ts  — inside the POST handler, before streamText
const today = new Date().toISOString().slice(0, 10);
 
// …then pass this as the system string:
system: `You are an assistant embedded in a Buildpad app. Today is ${today}.
 
When helping a user fill a form:
1. Call list_collections to discover the collection's fields and their types.
2. Call draft_item with your best interpretation of the user's description, using only the field names you found in step 1.
3. After calling draft_item, briefly summarise what you filled in and invite the user to review.
 
Format all date values as YYYY-MM-DD (e.g. ${today}). Never invent field names. Never call create or write operations — the user will save the form themselves.`,

// app/(authenticated)/tasks/new/actions.ts
"use server";
 
import { getAuthHeaders, getDaasUrl } from "@/lib/api/auth-headers";
 
export async function createTaskAction(data: Record<string, unknown>) {
  const url = `${getDaasUrl()}/api/items/tasks`;
  const headers = await getAuthHeaders();
  const res = await fetch(url, {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify(data),
    cache: "no-store",
  });
  if (!res.ok) throw new Error(`DaaS ${res.status}: ${await res.text()}`);
  return res.json();
}

// app/(authenticated)/tasks/new/page.tsx
"use client";
 
import { useState } from "react";
import { useChat } from "@ai-sdk/react";
import {
  Button,
  Divider,
  Group,
  Paper,
  Select,
  Stack,
  Text,
  Textarea,
  TextInput,
  Title,
} from "@mantine/core";
import { IconSparkles } from "@tabler/icons-react";
import { useRouter } from "next/navigation";
import { createTaskAction } from "./actions";
 
interface TaskFields {
  title?: string;
  priority?: string;
  due_date?: string;
  description?: string;
}
 
export default function NewTaskPage() {
  const router = useRouter();
  const [prompt, setPrompt] = useState("");
  const [fields, setFields] = useState<TaskFields>({});
  const [saving, setSaving] = useState(false);
 
  const { sendMessage, status } = useChat({
    // No `api` option — useChat posts to /api/chat by default
    onFinish: ({ message }) => {
      // Find the draft_item tool output in the completed message.
      // In ai v6 a tool part has type `tool-<toolName>` and its result
      // lives in `output` once `state === "output-available"`.
      const draftPart = message.parts?.find(
        (p) =>
          p.type === "tool-draft_item" &&
          (p as any).state === "output-available"
      ) as any | undefined;
 
      if (draftPart?.output?.fields) {
        const raw = draftPart.output.fields as TaskFields;
        // Normalize any date string to YYYY-MM-DD for the HTML date input
        if (raw.due_date) {
          const d = new Date(raw.due_date);
          if (!isNaN(d.getTime())) raw.due_date = d.toISOString().slice(0, 10);
        }
        setFields((prev) => ({ ...prev, ...raw }));
      }
    },
  });
 
  const handleFillWithAI = () => {
    if (!prompt.trim()) return;
    sendMessage({
      text: `Fill a new task form based on this: "${prompt}". The collection is "tasks".`,
    });
  };
 
  const handleSave = async () => {
    setSaving(true);
    try {
      await createTaskAction(fields);
      router.push("/tasks");
    } finally {
      setSaving(false);
    }
  };
 
  const isFilling = status === "streaming" || status === "submitted";
 
  return (
    <Stack gap="xl" maw={720} mx="auto" py="xl">
      <Title order={2}>New Task</Title>
 
      {/* AI Fill Panel */}
      <Paper withBorder p="md" radius="md">
        <Stack gap="sm">
          <Text fw={500} size="sm">
            Describe the task
          </Text>
          <Textarea
            placeholder='e.g. "Fix the login bug, high priority, due next Friday"'
            value={prompt}
            onChange={(e) => setPrompt(e.currentTarget.value)}
            rows={2}
            onKeyDown={(e) => {
              if (e.key === "Enter" && !e.shiftKey) {
                e.preventDefault();
                handleFillWithAI();
              }
            }}
          />
          <Button
            leftSection={<IconSparkles size={16} />}
            loading={isFilling}
            onClick={handleFillWithAI}
            variant="light"
            w="fit-content"
          >
            Fill with AI
          </Button>
        </Stack>
      </Paper>
 
      <Divider label="Review & edit" labelPosition="center" />
 
      {/* Form */}
      <Stack gap="md">
        <TextInput
          label="Title"
          placeholder="Task title"
          value={fields.title ?? ""}
          onChange={(e) => setFields((f) => ({ ...f, title: e.currentTarget.value }))}
          required
        />
        <Select
          label="Priority"
          data={["low", "medium", "high"]}
          value={fields.priority ?? null}
          onChange={(v) => setFields((f) => ({ ...f, priority: v ?? undefined }))}
          clearable
        />
        <TextInput
          label="Due date"
          type="date"
          value={fields.due_date ?? ""}
          onChange={(e) => setFields((f) => ({ ...f, due_date: e.currentTarget.value }))}
        />
        <Textarea
          label="Description"
          value={fields.description ?? ""}
          onChange={(e) => setFields((f) => ({ ...f, description: e.currentTarget.value }))}
          rows={3}
        />
        <Group justify="flex-end" mt="sm">
          <Button variant="default" onClick={() => router.back()}>
            Cancel
          </Button>
          <Button
            onClick={handleSave}
            loading={saving}
            disabled={!fields.title?.trim()}
          >
            Save task
          </Button>
        </Group>
      </Stack>
    </Stack>
  );
}