Ask AI

Maya can ask for a heading on the homepage hero without opening the composer. An agent starts the same Ask AI turn the panel starts, on the same account, and it spends the same credit. The panel is still the better door when she wants to watch the canvas and press Undo.

What you can do

Maya's homepage hero already has Text and Image on the canvas. She is in the agent, not in the composer. She can still ask for a heading above the first row. That is the same Ask AI the orange Ask AI button runs.

The panel is the better door for some jobs. The agent is better for others.

Use the agent when you are already in the chat and you want one change on a widget you can name: team, project, environment, widget.
Use the Ask AI panel when you want to watch the canvas, press Undo, or hit Stop without hashing the rows yourself.

A turn is one request

In the composer, Ask AI looks like a chat box. Under that, one request is a turn. The panel starts the turn, keeps going while Ask AI is still working, and shows you the result. An agent has to do those calls itself. The work is the same.

Starting a turn spends one Ask AI credit. The next step, and an answer to a question Ask AI asks, stay on that turn and do not spend another. A turn that fails, or that you cancel, still used the credit it started with. It is the same balance as the panel, on the same account that signed in when you connected MCP. Ask AI on rulesets spends that balance too, through its own conversation — this page does not start that one.

You need Composer Ai Editor under Widget Access, and Widget Access Manage or Admin on that environment. View can open the widget. It cannot start a turn. Staging and Production have their own Composer Ai Editor groups. Only the person who started the turn can read it, continue it, or cancel it.

Ask for the heading

Picture the homepage hero in Development. The words are the same ones the panel's empty state offers: add a heading above the first row.

Connect RuleCMS in the agent, if you have not. The steps are on MCP.
Name the team, the project, and the environment. Name the widget. Development is the usual place to try this. The widget has to exist already. Ask AI does not create one.
Hash the saved rows. That hash is how you say which copy of the widget you are looking at. The next section is the whole recipe.
Ask “add a heading above the first row”. The first reply is already the first step, not a promise that work will start later. It names the turn, says whether the widget changed, and says what Ask AI did in words.
If the turn is still working, take the next step. If Ask AI asked a question, answer it on this same turn. If it finished, open the widget. The heading is on the draft. Publishing is still a separate step.

{
  "entity": { "type": "widget", "id": "<the widget>" },
  "message": "add a heading above the first row",
  "documentHash": "<hash of the saved rows>"
}

entity.type is widget. A collection is refused. Ask AI only runs on widgets today, the same as the panel. overlayLayerIndex is optional. Send it when an overlay layer is what you are editing, so the change lands on that layer. Leave it off to edit the base. parentId can ride along and is stored. It does not turn collection editing on. Leave it off.

selectedColumnId and selectedRowId are optional. Send them when the sentence means “this column” or “this row” — the ids of what is selected now. Send them again on the next step if the selection moved. A message is at most 4,000 characters.

Hash the saved rows

Ask AI refuses to write when the copy you describe is not the one that is saved. That is how it avoids wiping a change you cannot see. The composer computes this for you. An agent has to send it.

Read the widget. The layout is itemList, stored as text. Parse that text.
Sort the keys of every object. Leave the order of rows and columns as it is. Leave out a key that has no value. Keep a null.
Take the SHA-256 of that JSON with no extra spaces, and write it as lowercase hex. That string is documentHash.

An empty widget is the text {"rows":[]}. Its hash is 1633902c6cbba5e7770dbed172df754a25078bb76efe1f23474edc87f1a47655. If your hash of that text differs, the hasher is wrong and every turn will be refused.

The widget may also carry a marker that changes when the draft is dirty. That marker is not this hash. Do not send it. When a step changes the widget, the reply includes a new documentHash. Send that one next. When a step does not change the widget, keep sending the hash that matched.

Read it, step it, answer it, or cancel it

The panel keeps calling until the turn stops. You do the same, one call at a time, and you stop when the status says to. Do not keep stepping a turn that has finished.

Status	What you do
`awaiting_step`	Ask AI is still working. Call step. No new sentence. Send the current hash, and the selection if it moved.
`awaiting_clarification`	Ask AI asked a question rather than guess. Answer with a message on this same turn. A new turn would forget the question and spend another credit.
`completed`	The request is done. Open the widget. Undo, if you need it, is in the composer.
`failed`	The reply says why. A request that needed more than ten steps was stopped. Ask for a smaller change.
`cancelled`	You stopped it. Nothing further will run.

Reading a turn gives you the status, how many steps have run, the sentences you sent, a short summary, and an error when there is one. It does not hand back the model's private tool transcript, or the whole widget. The start, step, and message replies are the ones that say whether the widget changed and, when it did, include the new rows and the new hash.

Cancel takes no body. It only works while the turn is still open — still working, or waiting on your answer. It stops the next step. It does not undo edits already written. Those stay on the draft until someone undoes them in the composer. A turn that already finished, failed, or was cancelled cannot be cancelled again.

When the panel is the better door

Use the Ask AI panel when the canvas is the point. You see the heading land. Undo is one click, and one request is one undo, even when it changed several things. Stop is the same button as Send. You never compute a hash. Autosave finishes before the turn starts, so you are not writing over your own unsaved work.

Use the agent when you are already there and you can name the widget. The menu of what you can ask is the same menu. “Make me a banner” disappoints in both places. The pieces — add this, move that, set this padding — are on What you can ask.

Names you may see

You do not have to type these. They are the labels in the agent's tool list, if you open it. Each one still checks Composer Ai Editor.

What you asked for	The tool
Start a turn and run the first step	`post_t_teamId_p_projectId_e_environmentId_composer_ai_turns`
Read the turn	`get_t_teamId_p_projectId_e_environmentId_composer_ai_turns_turnId`
Answer a question on that turn	`post_t_teamId_p_projectId_e_environmentId_composer_ai_turns_turnId_message`
Take the next step	`post_t_teamId_p_projectId_e_environmentId_composer_ai_turns_turnId_step`
Cancel it	`post_t_teamId_p_projectId_e_environmentId_composer_ai_turns_turnId_cancel`

When it does not land

What you see	What it usually means
You cannot run an AI composer edit	This account is missing Composer Ai Editor, or Widget Access Manage or Admin, on that environment. Ask a team administrator. The button in the composer is hidden for the same reason.
The team has no Ask AI credits	Nothing starts, and no credit is spent. Pay as you go includes no monthly credits until you buy a pack or subscribe to Core or Plus. That bill is separate from the RuleCMS plan, on the team's Ask AI billing page.
AI editing is only available for widgets so far	The entity was a collection. Open the widget, or edit the collection by hand. See Collections.
The widget changed while you were working	The hash does not match the saved rows. Read the widget again, hash the rows, and try again. In the composer you would reload.
Only the author who started this edit can continue it	Someone else on the team is holding the turn id. They can look at the widget. They cannot read, step, answer, or cancel this turn.
This edit has already finished	Cancel, step, or message ran after the turn completed, failed, or was cancelled. Read it. Start a new turn if you want another change. That spends another credit.
Ask AI is not set up for this environment	The composer hides the button for the same reason. The rest of the widget still works. This is a RuleCMS setup step, not a permission you can grant.