# Studio AI tools

## Bricks Technical Documentation

*What Studio AI can actually do — what the assistant can act on, how a two-phase orchestrator separates backend from frontend work, and the guardrails that keep it inside the platform.*

---

Studio AI is not a chatbot that writes code into a void. It is an agentic orchestrator that acts on your tenant through a fixed, audited set of **tools** — every table it creates, every workflow it wires, every file it edits is a named tool call against your tenant's real database and app. This page says what they act on, explains how a turn runs, and describes the gates that decide which tools are available when.

## Two phases, two agents

A Studio AI turn is split between two specialised agents drawing from one shared toolset:

- **The planner** does all *backend* work — schema, relationships, roles, permissions, workflows, concepts — and decides whether a turn also needs frontend work.
- **The frontend agent** writes and edits the app's SvelteKit files and assets when the planner asks for it.

Both draw from a single tool registry, and each phase then *filters* that registry down to the tools it is allowed to use. This separation is why the planner can safely reason about your whole app while only the frontend phase can touch app code — and why destructive schema changes are kept out of the planner entirely.

## What the assistant can act on

Every capability Studio AI has, grouped by what it acts on:

| Group | What the assistant can do |
|---|---|
| **The tenant** | Read tables, columns and the full configuration: roles, workflows, relationships, permissions |
| **Schema** | Create and change tables, columns and relationships. Altering a column, dropping a table and restoring a snapshot are guarded |
| **Roles** | Create, change and delete custom roles, see who holds them, set the role given at sign-up |
| **Permissions** | Set role permissions, anonymous read access and row ownership rules |
| **Workflows** | Create, change and delete workflows, check their health, inspect past runs (privacy-gated) |
| **App / frontend** | Create apps, read, search and edit their files, publish, check a deployment, read a build log, revert, rename, archive |
| **Boilerplate** | Check an app's version of the app base, assess an upgrade, upgrade, revert |
| **Media & assets** | Generate images, store images, documents and fonts, manage the media library |
| **Concept graph** | Navigate and inspect concepts, declare, retire and merge them |
| **Conversation** | Keep track of objectives and recall earlier messages |
| **Data flows / GDPR** | Check before using any third-party address, declare and list data flows |
| **Security (Grepleaks)** | Audit a workflow, a table or an app, check a scan, dismiss a finding |
| **Proposals** | Render a data model, business model or information architecture as a frozen diagram for review |
| **Reasoning memory** | Record and search why something was decided |
| **Artefacts** | Read any artefact, create or update tables, relationships, workflows, roles, permissions, integrations, components, retention policies and harnesses in one batch, move and rename files with their imports rewritten |

The concept-graph tools connect to [the concepts graph](/technical/concepts-ontologies); the data-flow tools connect to [data flows](/technical/data-flows); the workflow tools build the graphs described in [the RPC API & workflows](/technical/rpc-and-workflows).

## How a tool call runs

The assistant works in an agentic loop. Before each step it checks the wallet and the turn's spend; if there is room, it runs each tool the model asked for, feeds the results back, and continues until the model produces a final reply.

```mermaid
flowchart TD
  A["Model asks to use a tool"] --> B{"Budget left this turn?"}
  B -->|no| Z["Return the partial reply"]
  B -->|yes| C["For each tool call"]
  C --> D{"Tool allowed in this phase?"}
  D -->|no| E["Refuse with a steer<br/>(don't waste the turn)"]
  D -->|yes| F["Run against the tenant DB / API"]
  F --> G["Return the result"]
  E --> H["Feed results back to the model"]
  G --> H
  H --> A
  H --> J{"Model done?"}
  J -->|yes| K["Post-process and deliver the reply"]
```

## Phase gating

The full toolset is filtered per phase, and the gate is enforced in two layers:

- **The allowlist.** The planner gets all the inspection, workflow, role, permission, concept and proposal tools, plus the batch schema-authoring surface. The frontend agent gets the app-file and asset tools, plus the sensitive schema-mutation tools. **Destructive schema changes — altering a column, dropping a table, restoring a snapshot — are deliberately *not* in the planner's set**; the planner signals that a turn needs frontend work rather than performing them itself.
- **Defense in depth.** Because a model can technically emit any tool name, a guard rejects a filtered-out tool with a steering message instead of running it or wasting the turn. On top of that, the most sensitive schema mutations additionally require **Heavy Reasoning** to be enabled, and refuse in standard mode with a clear message.

```mermaid
flowchart LR
  R["Full tool registry"] --> P{"Which phase?"}
  P -->|planner| PT["Inspection · workflows ·<br/>roles · permissions ·<br/>batch schema authoring"]
  P -->|frontend| FT["App files · assets ·<br/>schema mutations"]
  PT --> PX["No column-alter /<br/>table-drop here"]
  FT --> HG{"Heavy Reasoning on?"}
  HG -->|no| REF["Destructive edits refuse:<br/>'enable Heavy Reasoning'"]
  HG -->|yes| RUN["Mutation runs"]
```

## Guardrails

Several protections are built into the orchestrator, not left to the model's good behavior:

- **Privacy-gated execution inspection.** The one tool that reads real end-user data from workflow executions requires a one-line privacy notice and your acknowledgement before it runs — it is never treated as a no-permission read.
- **Non-system roles only.** The assistant (and the workflows it builds) can manage custom roles but never administrative ones.
- **No hallucinated links.** The assistant is forbidden from sending you to internal `/rest/v1` or `?debug` URLs, and stray tool-call markup is stripped from prose.
- **Bounded history.** Publishing an app prunes old versions rather than letting history grow without limit; boilerplate upgrades keep a short-lived snapshot you can revert to.
- **Read de-duplication.** Redundant identical reads within a phase are short-circuited — except for probes whose results legitimately change (deployment checks, execution inspection, build logs).

## Worth knowing

- **The planner cannot make destructive schema changes** — by design; that work is gated to the frontend phase and Heavy Reasoning.
- **Some tools are declared but refuse without an integration** — the security-audit tools require the Grepleaks integration to be active; the tools always appear, but each refuses cleanly when the integration is off.
- **The assistant prepares, you decide** — data-flow declarations are prepared unsigned and require a human to sign; proposals are rendered for review rather than applied silently.

---

*This page describes shipped behavior. Studio AI is the paid surface behind [Brickify's](/technical/brickify) conversational path, and it reads and writes the structures described across the rest of this technical documentation set.*
