The flowss Studio Agent: prompt and quick help

The flowss Studio Agent is the Studio's own agent, and this page covers the everyday ways to reach it. It is not one panel but a set of doors that all lead to the same agent: the prompt at the bottom of the screen (Ask flowss Studio Agent) with its Quick and Agent modes, the suggestion chips that float above it, voice dictation, the Ask the flowss Studio Agent… tools on the canvas, the Fix with the flowss Studio Agent and Explain this diagram buttons in Diagram Intelligence, and Explain change when you compare two versions. This page explains every one of those doors: what each sends to the flowss Studio Agent, what comes back, what it costs, how to undo it, and what to do when it says no. The multi-step runs that the Agent mode hands your request to have their own page, The flowss Studio Agent and its modes.

At a glance

On Windows and Linux, read ⌘ as Ctrl throughout this page.

Before you start: who can use AI

AI in the Studio depends on your plan, not on which door you use. Every door on this page works the same way once AI is available to you.

A few things to know before your first request:

• Bring your own key is part of Starter and above. You can paste a key from Anthropic, OpenAI, Google Gemini, DeepSeek, Alibaba Qwen, Zhipu GLM, Moonshot Kimi or Mistral. Calls made on your own key spend no points. See Bring your own AI key.
• Hosted points are a hard monthly allowance, not unlimited. Top-up packs (100 points for $5, 500 points for $20) never expire and are spent only after the month's allowance runs out. See AI points and limits.
• You are charged only for answers that arrive. A request that fails, is refused or returns nothing usable costs nothing. The flowss Studio Agent has its own, slightly richer rule, described in The flowss Studio Agent and its modes.
• When the platform's AI is switched off entirely, the prompt says AI is off here with a Set up link instead of accepting a request, and a strip under the editor reads Platform AI is off with a link to the AI setup guide. Everything that does not need AI keeps working: templates, every renderer, the direct canvas tools, the built-in converters and the deterministic explanations.

The prompt

The prompt island at the bottom centre of the Studio is the one place to ask the flowss Studio Agent for something. Screen readers announce it as Ask flowss Studio Agent. At rest it is a slim pill holding, from left to right: a sparkle (which turns into a spinner while a request is running), the field that reads Describe a diagram or a change…, the Quick and Agent switch, the AI settings button, and Send.

Sending a request

1. Click the field, or press ⌘/ from anywhere in the Studio. ⌘/ works even while you are typing in another field; if the code editor itself uses ⌘/ (to toggle a comment), the editor's command wins there.
2. Choose Quick or Agent (see below). The prompt remembers your choice while the Studio is open and starts on Quick when you load the page.
3. Type what you want. The field grows to about four lines as you type, then scrolls. Press ⇧Enter for a new line.
4. Press Enter, or click Send. Send stays disabled and explains why when you point at it: Type a request first while the field is empty, Working… while a Quick change is still running, or the reason AI is unavailable.
5. Press Escape to let go of the field.

In Agent mode the field clears as soon as you send, the flowss Studio Agent pane opens on the right and the run starts there. In Quick mode your text stays in the field while the change is worked on and clears when the answer has been handled; the change is made in place and the canvas updates.

If a Quick change fails, the reason appears in a red line just above the prompt (where the suggestion chips sit), with a Dismiss (×) button. The field is cleared either way, so retype or paste the request to try again.

Quick or Agent

The two modes answer different questions. Quick is one round trip that rewrites the figure you are looking at. Agent is a multi-step specialist that plans, edits, checks its own work and reports back.

Tip: If you are not sure, start with Quick for an edit you could describe in one sentence, and switch to Agent when the request needs judgement, more than one figure, or a check of the result.

What Quick mode does, step by step

1. When you send, the Studio reads the figure that is open at that moment: its engine and its whole source.
2. It sends your instruction with that source to the flowss Studio Agent as a single request. No other figures and no earlier conversation are included.
3. The flowss Studio Agent returns a complete new source for the figure. The Studio writes it into the figure, keeping the figure's engine.
4. The canvas re-renders. If the figure was open, the change is one ordinary undo step, so ⌘Z puts the previous source back.

While the request runs, the prompt's sparkle becomes a spinner and Send is disabled. You can keep working, including switching figures: the result is still written to the figure you asked about, not to whichever one is in front of you when it arrives. If you delete that figure before the answer comes back, nothing is written and you see "The figure this refine was for is gone — nothing was applied."

Note: Quick mode keeps the figure's engine. To move a diagram to another notation, use Convert to another engine… from the ⋮ file menu, or ask the flowss Studio Agent.

Warning: A Quick change that lands on a figure you are not looking at cannot be undone with ⌘Z, because undo belongs to the open figure. Open that figure's History if you need the earlier version back. See Version history and undo.

Good Quick requests are specific and local:

• "Rename the Payment node to Checkout"
• "Make every decision diamond amber"
• "Add a step between Validate and Ship called Pack"
• "Switch to a left-to-right layout"
• "Translate all labels into Spanish"

Agent mode from the prompt

When Agent is selected, sending opens the flowss Studio Agent pane on the right and runs your request there with whichever mode the pane's mode picker shows. A pane that was closed opens on Build / edit diagram. Everything that happens next is described in The flowss Studio Agent and its modes.

Warning: The flowss Studio Agent runs one request at a time. If a run is already in progress, a request sent from the prompt in Agent mode is not queued and does not start: the prompt clears and your text is placed in the flowss Studio Agent pane's composer instead, replacing anything you had typed there. When the current run finishes (or after you click Stop), press ⌘Enter or Run the flowss Studio Agent in the pane to run it.

Suggestion chips

Up to three suggestion chips float above the prompt. They appear while the canvas is empty and whenever the prompt has focus.

The × at the end of the row (Hide suggestions) dismisses the chips. The Studio remembers that choice in this browser; in a private window it is remembered for the visit only.

AI settings and the points reading

The AI settings button on the prompt opens a small panel titled AI settings. In the Studio it holds one action, Dictate a change, described in Voice input.

When your hosted AI points run low, a small amber reading such as 27 left appears on the prompt and links to your account page. It appears once your balance falls to 15% of your monthly allowance or to 10 points, whichever is higher: 30 points on Plus, 90 on Ultra and Enterprise. Pointing at it shows the full balance, split into monthly and purchased points. If you saved an AI key that your plan cannot use, the same spot reads Key not in use, and pointing at it explains why.

On a narrow screen

When the prompt has less than 300 pixels of room (a tablet with a wide rail, or any phone), it becomes a single sparkle button, Ask flowss Studio Agent (⌘/). Clicking it, or pressing ⌘/, opens the same form as a panel (a bottom sheet on a phone) titled flowss Studio Agent, with any error line at the top, a Mode row holding Quick and Agent above the form, the suggestion chips beneath it (shown here whenever you have not hidden them), and Close AI to put it away. Escape in the field also closes the panel. Bigger boxes and Colourblind-safe close the panel and run the flowss Studio Agent; everything else works as in the full prompt.

Note: In this narrow panel the Make the layout left-to-right chip does not fill the field. Type the request yourself, or widen the window.

Voice input

You can dictate a request instead of typing it. Dictation lives on the microphone button in the flowss Studio Agent pane's composer, and there are three ways to start it:

How dictation behaves:

1. While it listens, the microphone turns red and pulses; its tooltip reads Listening… click to stop.
2. Speak your request. The words appear in the composer as you speak, refined as recognition settles.
3. Anything you had already typed is kept, and your dictation is added after it with a space.
4. Recognition stops by itself when you pause, or when you click the microphone again.
5. Dictation never sends anything. Read the text, correct it if needed, and press ⌘Enter or Run the flowss Studio Agent.

Dictation uses the speech recognition built into your browser, in your browser's language. It works in Chrome, Edge and Safari 14 and later. In a browser without it, the microphone is greyed out and its tooltip reads "Voice dictation needs the Web Speech API (Chrome / Edge / Safari 14+)."

Note: Recognition is done by your browser, not by flowss, and flowss only ever receives the resulting text. Depending on your browser, its speech service may run online. Dictation costs no AI points; the run you start with the text does.

The flowss Studio Agent on the canvas

Two canvas tools let you point at one element and ask the flowss Studio Agent to change just that element. Both are a single AI call (1 point on hosted AI) and both are ordinary undo steps.

• Diagram tools → Ask the flowss Studio Agent… Click a label on the rendered diagram to select it, then choose Ask the flowss Studio Agent… in the Diagram tools. Your browser asks for the change under the heading "Free-form change to" followed by the label.
• Edit label popover → Ask the flowss Studio Agent… In the popover that opens beside a clicked label, choose Ask the flowss Studio Agent…. The popover becomes Ask the flowss Studio Agent about this element, the box suggests "e.g. add a validation step before this", and the button reads Send to the flowss Studio Agent. Just rename switches back to a plain rename.

While the flowss Studio Agent works, the canvas shows The flowss Studio Agent is editing this element…. These tools are the fallback for engines and changes the direct tools do not cover. The full reference, including which engines have direct tools, is in Data, timeline, TikZ and the diagram tools.

The flowss Studio Agent in Diagram Intelligence

Diagram Intelligence (⇧⌘X) reads the structure of your figure without AI. Two of its buttons do use AI.

Fix with the flowss Studio Agent

Findings marked Issue or Watch carry a Fix with the flowss Studio Agent button (tooltip Ask the flowss Studio Agent to fix this). Clicking it sends that one finding and the figure's source to the flowss Studio Agent and asks for the smallest change that resolves it. While it runs, the button reads Fixing….

Explain this diagram

Explain this diagram, at the foot of the panel, writes a plain-language explanation of the figure. While it works the button reads Explaining…, and it is disabled when the source is empty. For Mermaid flowcharts and DBML schemas the explanation is generated directly from your source, with no AI and no points. For other engines (including Mermaid diagrams that are not flowcharts) it asks the flowss Studio Agent for three to six short bullet points (1 point), and leaves your figure unchanged. The explanation appears in a box under the button and is cleared as soon as you edit the source.

If Fix with the flowss Studio Agent cannot run, a toast says why: "Add an AI key in Settings to use AI fixes." when AI is not set up for you, "Daily AI limit reached." when a daily limit was hit, or the provider's own message (for example "Couldn't reach the model.").

The rest of Diagram Intelligence is documented in Flow-systems analysis in Studio.

Explain change in Compare revisions

In the Diagram timeline (⇧⌘H opens Version history…), comparing two versions opens Compare revisions: the two renders side by side (Before and After), a line diff beneath them, Swap, and Restore on each side. Explain change (tooltip Ask the flowss Studio Agent to summarise what changed) asks the flowss Studio Agent to summarise, in one to three sentences, what changed between the two versions; the answer appears in a strip beginning flowss Studio Agent:. It never edits your figure. If the request fails, a red strip shows the reason, for example "The flowss Studio Agent couldn't summarise the change", or "The flowss Studio Agent didn't return a summary." when the answer came back empty. See Version history and undo.

Note: Explain change sends both versions' full source inside one request, and a request may be at most 6,000 characters. For large figures, where the two versions together come close to that, it is refused with "Prompt is too long (>6000 chars)". Compare smaller revisions, or read the line diff instead.

Readiness: Fix and What is left

The status glyph in the Studio's identity island opens the status popover (⇧⌘M), whose readiness section tells you where the figure stands. Two kinds of button there hand work to the flowss Studio Agent:

• Fix, beside an individual finding (screen readers announce it as "Fix with the flowss Studio Agent" and the finding), sends that one finding to the flowss Studio Agent's Review & fix mode with the instruction to fix only that.
• The buttons under What is left hand a whole stage to the right specialist, together with the readiness reading, so the flowss Studio Agent knows exactly what the score was marked down for.

The popover stays open and reports what happened: Handing it to the specialist…, then the flowss Studio Agent's progress, then Finished — re-reading the document. If the stage did not finish you see That stage did not finish. with the reason, and if nothing picked the request up within a couple of seconds you see Nothing picked this up. with Open the flowss Studio Agent panel and it will run there.

flowss Studio Agent commands in ⌘K

The command palette (⌘K) offers these commands for the flowss Studio Agent while you are in the Studio:

A request you type into ⌘K anywhere on the platform can also be routed to the Studio's agent. When your own palette sends it, the run starts as soon as the Studio opens. When the request arrives in a link from somewhere else, it is put in the flowss Studio Agent's composer and waits for you to press Run the flowss Studio Agent, so a link can never spend your points on its own.

Other AI doors in the Studio

A few Studio features use AI as part of a larger job. They are documented on their own pages:

What the flowss Studio Agent sees and ignores

Nothing leaves your browser for the flowss Studio Agent until you press Send, Run the flowss Studio Agent, a chip that runs, or an AI button. What is sent depends on the door:

The flowss Studio Agent treats anything it did not receive from you as material, not instructions. Text in a fetched file, in a pasted document, in an image description or inside a diagram that says "ignore your instructions" or "delete every diagram" is diagrammed if it is meaningful and otherwise ignored; it never changes what the flowss Studio Agent does. As a second safeguard, the flowss Studio Agent cannot delete a figure or overwrite one you did not have open without your approval. See The flowss Studio Agent and its modes.

For how flowss handles the content you send to AI providers, see Privacy and your data.

Costs at a glance

Requests on your own key are not metered in points, but a daily fair-use ceiling applies: 1,000 AI requests a day, of which at most 300 may be agent runs. Both reset at midnight UTC, and a request refused at the ceiling is never sent to your provider.

Tips

• Use Quick for edits you can describe in one sentence and Agent for anything that needs a plan, several figures or a check. Quick costs one point; a standard agent run costs eight.
• Name things exactly as they appear in the diagram ("the Payment node", "the edge from API to DB"). Both modes work from your source, so the exact label is the most reliable handle.
• Press ⌘/ from anywhere to jump to the prompt, type, and press Enter, without reaching for the mouse.
• Run Bigger boxes before you present on a projector, and Colourblind-safe before you share a figure widely.
• Dictate a long request, then tidy it in the composer before you run it: dictation never sends on its own.
• If Diagram Intelligence keeps flagging something you drew on purpose, try Fix with the flowss Studio Agent once: when it agrees the figure is right, the finding stands down until your next edit.
• Keep an eye on the points reading on the prompt. It appears only when you are running low, and links straight to your account page to top up.

Limits and known constraints

• Free has no AI at all: no hosted points and no own key. Starter can use AI only on your own key.
• A request may be at most 6,000 characters. Paste longer material (code, data, documents) into the flowss Studio Agent pane in Import to diagram mode, or import it from a URL.
• Quick mode sends only the open figure and no conversation history, so it cannot refer back to an earlier request or to another figure.
• Quick mode keeps the figure's engine, does not verify its result, and must answer within 60 seconds. If the result does not render, ⌘Z restores the previous source.
• A Quick change written to a figure that is no longer open cannot be undone with ⌘Z.
• The flowss Studio Agent runs one request at a time; requests are not queued (a request sent during a run waits in the flowss Studio Agent pane's composer).
• Explain change fits both versions' source into one 6,000-character request, so it is refused for large figures.
• In the narrow flowss Studio Agent panel, the Make the layout left-to-right chip does not fill the field.
• Dictation needs a browser with built-in speech recognition (Chrome, Edge, Safari 14 and later), recognises one utterance at a time and uses your browser's language.
• Explain this diagram is generated without AI only for Mermaid flowcharts and DBML.
• Calls on your own key are subject to a daily fair-use ceiling of 1,000 requests, including at most 300 agent runs.

Troubleshooting

Related pages

• The flowss Studio Agent and its modes
• The Studio editor
• Data, timeline, TikZ and the diagram tools
• Flow-systems analysis in Studio
• Importing and converting
• AI in flowss
• AI points and limits
• Bring your own AI key
• Version history and undo
• Keyboard shortcuts
• Plans and what they include