---
id: ai-assistant
title: "The assistant"
summary: "Viaducta AI in the designer builds, changes, explains and fixes flows. Agent, Ask and Plan modes, approvals and permission modes, production safeguards, error analysis, chats, attachments, memory, skills and usage."
audience: user
keywords: "ai, assistant, viaducta ai, agent mode, ask mode, plan mode, approval, permissions, memory, skills, attachments, analyze with ai, fix with ai, revert, usage, tokens"
---
# The assistant

**Viaducta AI** works in the designer next to you. Describe what a flow should do and it builds it: components,
connections, configuration, types and scripts. It explains flows, changes them, runs and debugs them, reads the logs,
and fixes the errors it finds. Open it from **Viaducta AI** in the left rail, as a floating window or as a tab.

## What it can do

- **Build and change flows.** Create a flow, add and configure components, connect them, write scripts in C#,
  Python and JavaScript, create types (also from a JSON sample) and arrange the layout. A set of changes is applied
  as a whole: if one step fails, nothing is changed.
- **Run and inspect.** Validate, compile, start, stop and debug flows, set breakpoints, capture a record on a
  connection with the data monitor, run flow tests, and read logs and alarms.
- **Explain.** Walk through what a flow does, why a component is configured the way it is, or what a plugin offers.
  It reads the same plugin reference you find under [Plugins](/documentation/plugins/).
- **Fix errors.** Every error in the log viewer, the trace console and the flow messages offers **Analyze with AI**
  (explain the cause, change nothing) and **Fix with AI** (find the cause and fix the flow).
- **Port existing integrations.** Attach source code, configuration files or a zip archive of a project, and ask the
  assistant to rebuild it as Viaducta flows.
- **Work with the repository.** Browse folders, compare and restore flow versions, test database links and explore
  database schemas. It sees the names of expression settings, never their values.

## Modes

Pick the mode in the chat, or start a message with `/agent`, `/ask` or `/plan`.

| Mode | What the assistant does |
|---|---|
| **Agent** | Makes changes to your flows and other objects. |
| **Ask** | Answers questions only; changes nothing. |
| **Plan** | Produces a plan and a to-do list without changing anything. You review it on the **Plan** card and choose **Approve & execute**, or **Revise…** to send it back. Approving switches to Agent mode and carries out the plan. |

## Approvals

Every action the assistant takes is classed as reading, editing, executing (run, stop, debug) or destructive
(delete, restore). The shield menu in the chat sets how much it may do without asking:

| Permission mode | Asks before |
|---|---|
| **Ask before changes** | every change |
| **Auto-edit** (default) | running, stopping, deleting, database links and restores |
| **Auto** | nothing, except in production |

When the assistant needs approval it shows an **Approval needed** card with **Approve**, **Deny** and **Always allow**
(for the rest of the conversation).

**Production environments always ask.** An environment whose name matches the production pattern (by default any
name containing `prod`) requires approval for every change, whatever the permission mode, and **Always allow** is
not offered there.

## Undo

Every turn has a **Revert** link that puts the flows the assistant changed back to their state before that turn.
Flows it created in that turn are kept. Save afterwards to keep the reverted state.

While it works you can **pause**, **resume** or **stop** it. With **Follow agent** on, the flows it edits come to the
front so you can watch the changes.

## Chats

Chats are kept per execution environment and are visible to everyone in it, grouped by **This flow**,
**Repository**, **General** and the chats of external agents. Filter by **All** or **Mine**, pin, rename, archive,
and export a chat as Markdown or JSON. The assistant can search earlier chats when you refer to past work.

In the message box, type `/` for commands and `@` to mention a flow, a component or an attached file:

| Command | Does |
|---|---|
| `/new` | Starts a new chat. |
| `/compact` | Summarises the earlier conversation to free context. Done automatically when the context is 70% full. |
| `/agent`, `/ask`, `/plan` | Switches the mode, optionally with a message. |
| `/cost` | Shows the token usage and cost of the chat. |
| `/export` | Exports the chat (`/export json` for everything stored). |
| `/help` | Lists the commands. |

## Attachments

Attach files with the paperclip, or drop or paste them into the chat:

- **Documents:** PDF (text layer) and Word `.docx`, read as text.
- **Images:** PNG, JPEG, GIF and WebP, when the model understands images.
- **Source and text files** of any kind, read as text.
- **Zip archives:** unpacked into a temporary workspace the assistant can browse, up to 5,000 files and 200 MB.

Up to 30 MB per file and 300 MB per chat. Long pasted text (over 3,000 characters) becomes an attachment
automatically.

## Memory and skills

**Memory** keeps facts, preferences, conventions and decisions across chats: for you only, for a flow, for a folder
or for everyone in the environment. The assistant saves your personal notes on its own and shows them with **Undo**.
Anything for others, anything it learned from tool output, and anything in production waits for you on a
**Remember this?** card. It never stores secrets.

**Skills** are named procedures the assistant follows, such as "how we build a polling import". You create them in
the chat or on the **Memory** tab, and import or export them as `SKILL.md` files. Every new or changed skill is
confirmed on a card before it is saved.

## Usage

Each turn ends with a line of model calls, tokens in and out, and duration. Under the message box you see the model,
the mode, how full the context is and the tokens of the chat, with the cost when prices are configured. The **Usage**
tab shows the environment's usage by model, purpose, person and chat. Administrators also get an **Admin** tab with
backups, retention rules and the audit log.

## Who can use it

Designers, viewers and administrators can chat with the assistant. Shared memories and skills are managed by designers and administrators, and the assistant's data store by
administrators.

The administrator decides which model provider the assistant uses; see [Providers and setup](./providers).