AI Builder

The AI Builder is the primary way customers extend ObjectOS. Open ObjectOS, describe what you need in plain language, and it builds the metadata for you — objects, fields, views, dashboards, flows, whole apps. Nothing is built until you approve the plan, and everything it builds is ordinary ObjectStack metadata you can read, change and package.

Two agents: the Builder and the Assistant

ObjectOS ships two AI agents. You do not choose between them: where you ask decides which one answers.

Both run as the signed-in person. Every tool call is checked against that person's permissions, record access and field-level security, so the AI can never see or change more than they could themselves.

Who can use the Builder. An AI seat alone is not enough: the Builder changes your app's metadata, so it also needs the manage_metadata or studio.access permission. A member without either sees only the Assistant, a direct request to the Builder is refused with 403 PERMISSION_DENIED, and every build tool checks the permission again when it runs.

Try it

You: I need to track customer support tickets.
     Each ticket has a subject, description, priority (low/medium/high/urgent),
     status (new/open/pending/resolved/closed), and assignee.

AI:  Here's the plan:
     • Object `support_ticket` with 5 fields
     • A kanban view grouped by status
     • A dashboard of open tickets by priority
     • A few sample tickets to try it with

     Shall I build it?

You: Yes

AI:  ✓ Object created
     ✓ Kanban view and dashboard created
     ✓ Sample data added
     Published — open Support Tickets to try it.

You now have a working ticketing app — REST endpoints, generated views, audit log entries, permission checkpoints, the works. No file was edited; no restart happened.

How a build runs

1. Plan. For anything larger than a single change — "build me a recruiting system" — the Builder first proposes a blueprint: the objects, fields, relationships, views, dashboards and sample data it intends to create, with its assumptions. Nothing is created at this step.
2. Approve. You answer in the chat: approve it, or ask for changes and get a revised plan. The Builder makes changes only after you approve them in that conversation.
3. Build as drafts. The approved changes are written as drafts — staged, not yet live.
4. Verify. The Builder checks the drafts against the platform's rules and fixes what it can before anything goes live.
5. Publish. The drafts are published into the environment you are building in, and the app appears there with its sample data. A status panel shows what has actually been published; the Builder never reports a change as shipped when it is not.

To extend an existing app, say so — "add a satisfaction survey to the support app" — and the Builder designs the new pieces to link to that app's objects and adds them to its navigation, instead of building a separate app.

What you can ask for

If the AI can't do it, it says so — and points you at the manual path.

The tools the agents call

An agent's abilities are its tools. See the live catalog for an environment at GET /api/v1/ai/tools.

The Builder's authoring tools work on packages and their metadata, and are validated against @objectstack/spec:

The Assistant's data tools read and act on records:

aggregate_data is part of the in-product AI. An agent connected from outside over MCP gets its own tool set, described there.

Actions as tools

An action becomes a tool named action_<name> when its author exposes it to AI — ai: { exposed: true } with an ai.description of at least 40 characters, on a type that runs without a UI (script, flow or api). Once exposed, the AI can call it like any built-in tool, under the caller's permissions; an action that is not exposed never becomes one. See Actions.

Approval before an action runs. An action that declares ai.requiresConfirmation: true — or looks destructive without declaring otherwise — is not run straight away. The AI files it as a pending action, and it runs only when approved:

A pending action belongs to the person whose conversation proposed it: only they can read, approve or reject it. Anyone else, an administrator included, is answered as if it did not exist.

Chatting through the API

Send a conversation to an agent by name, ask or build:

curl -X POST https://your-environment-host/api/v1/ai/agents/ask/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{ "role": "user", "content": "How many open opportunities over $50k?" }],
    "context": { "appName": "crm", "objectName": "opportunity" }
  }'

• messages — the conversation so far. Only user and assistant turns are accepted from the client.
• context — where the person is: appName, objectName, viewName, recordId. Skills use it to decide what is relevant.
• conversationId (optional) — continue an existing conversation.

Answers stream by default as Server-Sent Events (the Vercel AI data stream protocol, x-vercel-ai-ui-message-stream: v1); charts arrive in the stream as data-chart parts. Send "stream": false for a single JSON answer instead.

Conversations are kept under /api/v1/ai/conversations, and each person sees only their own.

Limits

• Data access follows the person's own permissions, for reading and for actions alike.
• System packages are off limits. Asking the AI to change a system package (sys_*) is refused.
• Large builds go better in steps. "Build a full HR app" works, but a series of smaller conversations, each landing one area, is easier to review.
• On ObjectOS Cloud, the AI draws on the environment's AI allowance, and an environment holds at most 500 unpublished drafts (Storage and Limits). On a self-managed Enterprise deployment the model is your own, configured in AI Service.

Going beyond build-time AI

The same AI plumbing powers runtime agents for your end users — support assistants, sales co-pilots, internal Q&A bots — built on the same Agent → Skill → Tool architecture. See Agents.

Where to go next

• Agents — end-user assistants on top of your data
• Data Model — what the AI is actually generating
• Actions — the unit the AI exposes as runtime tools
• AI Credits and Limits — the AI allowance on ObjectOS Cloud
• AI Service — provider config (OpenAI / Anthropic / Google / DeepSeek / …)