Working with the AI agent

Every project has an AI agent that plans, designs, and codes for you. You describe what you want in plain language. The agent writes the Dart code, updates your screens, and repairs its own mistakes.

The agent is powered by the fluttergo-pipeline skill system, a catalogue of Flutter-specific skills (scaffolding, screens, theming, navigation, state management, backend wiring, automatic repair) that the agent selects from on every run. You saw the skill chip on the studio home; it is attached to every prompt automatically.

You never need to write code yourself. But you do steer the agent: what mode it runs in, which pages it touches, and what references it uses. This chapter explains every control, one small step at a time.

The build pipeline: every prompt goes through the same five stages, and you iterate by sending the next prompt.

What you need#

• You have signed in and created a project (Getting started).
• Your project is open, so you can see the conversation panel on the left.
• Optional but recommended: connect GitHub first, so every agent change is saved as a safe point (Save your code to GitHub).

How to do it#

1. Find your way around the workspace#

Open your project. Everything you need is on one screen.

The workspace. You talk to the agent in area ②; results appear in ③ and ④.

2. Locate the prompt box (the composer)#

At the bottom of the conversation is the composer. It shows the placeholder "Describe what you want to generate…". Type here. Under the box you'll see the hint "⌘/Ctrl + Enter to send · include goals, content, style, and format".

3. Pick a mode, Ask or Design#

To the left of the composer is the mode selector. Click it to see two modes:

• Ask, Ask mode is "For quick answers, edits, planning, and discussion without assuming a design artifact must be created." Use it to clarify ideas, compare options, or ask questions about existing work.
• Design, Design mode is "For creating or changing concrete outputs: pages, prototypes, live artifacts, slides, images, videos, HyperFrames, audio, dashboards, and project files." Use it when you want the agent to generate or change files.

The popover shows a Best for section and Try asking examples for each mode.

4. Scope the prompt with chips#

The chips above the prompt box control exactly what the agent touches:

• Design system chip, switch which system styles the generation. The picker is titled "Choose a design system"; choose "None, freeform" to not anchor to a system this turn. On the studio home this defaults to Auto, which "automatically matches the best design system and visual style for the current prompt."
• Editing chip (current design file), when a design file is open, the composer shows a chip labeled Editing with the file name, and the placeholder changes to "Ask FlutterGo AI to change {file}...". Your prompt is scoped to that open file instead of the whole app.
• App pages, a Flutter-only selector. It shows "All pages ({count})" by default; tag pages and it shows "{count} pages tagged". Use "Search pages…" to find one quickly.
• Skill chip, shows the active skill as Skill: {title} (for example the fluttergo-pipeline skill on Flutter projects). Use Clear active skill to remove it.

5. Add references#

Click the + button (tooltip: "Attach files (or paste / drop)") to attach screenshots, images, or documents. You can also paste an image from your clipboard or drop a file onto the composer. Type @ to mention things, the search prompt says "Search Design Files, tabs, plugins, skills, MCP servers, and connectors."

Prefer talking? Click the microphone button labeled Dictate. While it is active it shows "Listening… click to stop".

6. Send, and watch the agent work#

Press ⌘/Ctrl + Enter or click Send. The agent plans, edits files, and streams its progress into the conversation. While it runs, the Send button becomes Stop, click it to cancel the run.

7. Review the result#

When the run finishes, the agent's reply includes preview action buttons (Run / reload) so you can see the change immediately, you rarely need to reach for the preview rail. To read the generated Dart, use the Show code toggle on the preview (details in Prompt, design & code generation).

Success: If your project is connected to GitHub, every completed agent run is pushed automatically as a safe-point commit, "FlutterGo: apply AI changes".

Writing good prompts#

You don't need technical language. These all work:

• "A recipe app with a home feed, search, and a detail page with ingredients and steps."
• "Make the onboarding 3 swipeable pages with illustrations and a Get Started button."
• "Change the primary color to deep purple and use rounded cards everywhere."

Rules of thumb that consistently get better results:

Tip: Tag only the pages you care about in App pages before sending. A scoped prompt is faster and cannot accidentally change other screens.

Important: The agent changes real project files. If you want a safety net for experiments, connect GitHub first, undo is then one message: "revert the last change".

Common mistake: Sending a long wish-list in one message. The agent will try, but results are much better one goal at a time.

Automatic repair#

After each change the agent runs flutter analyze and fixes what it finds, compile errors, broken layouts, bad network images, and web-preview issues are repaired without you asking. If a build still fails, paste the error you see into the conversation; that's all the agent needs. See Testing & debugging.

Troubleshooting#

Problem: The Send button does nothing. Possible causes: The prompt box is empty, or a run is already in progress. Solution:

1. Type something first, the composer needs text to run.
2. If a run is active, wait for it to finish or click Stop.

Problem: The agent changed a different screen than I meant. Possible causes: The prompt did not name the screen; all pages were in scope. Solution:

1. Say "revert the last change".
2. Open App pages and tag only the target page.
3. Re-send the prompt and name the screen in the text too.

Problem: Dictate shows "Microphone permission denied". Possible causes: The browser blocked microphone access. Solution:

1. Click the permissions icon in your browser's address bar.
2. Allow the microphone for this site.
3. Click Dictate again. If it fails with "Voice input failed, try again", retry once, this is usually temporary.

Problem: The reply stopped with a connection error. Possible causes: "The connection to the model service dropped before the response finished, usually an unstable network or proxy." Solution:

1. Check your network.
2. Send the prompt again, your project files are unchanged unless the reply reported edits.

FAQ#

Do I need to pick a skill myself? No. On Flutter projects the fluttergo-pipeline skill is attached automatically. You only touch the skill chip if you want to clear or change it.

What is the difference between Ask and Design mode? Ask answers questions and helps you plan without creating files. Design creates or changes concrete outputs, screens, code, and project files.

Can I stop the agent mid-run? Yes. Click Stop (it replaces Send while the agent runs).

How do I undo something the agent did? Say "revert the last change" in the conversation. If GitHub is connected, you can also restore any commit from your repository history.

Can I attach a design screenshot and say "make it look like this"? Yes. Click + (or paste / drop the image) and describe what you want copied, layout, colors, or both.

Does the agent see my whole app on every prompt? By default yes. Use the App pages selector or open a file (the Editing chip) to narrow the scope.

Where to go next#

• Prompt, design & code generation, a deep dive into modes, skills, and the code view.
• Preview, run & build, run and test what the agent built.
• Save your code to GitHub, safe points and version history.