Assistants (Agents)
An Assistant (internally an agent) is the unit of work in RondoFlow. Each Assistant has a personality, a model, a set of tools it may use, and optional Skills, Connections, and Memory. You wire Assistants together on the Workspace to build Workflows.
You configure an Assistant through its agent drawer — the panel that slides in from the right when you open an Assistant card on the Workspace.
Creating an Assistant
The palette ships three Assistant cards, one per provider. The card you drag fixes the Assistant’s provider for its lifetime (provider is read-only in the drawer):
| Palette card | Provider | Runs via |
|---|---|---|
| Assistant | claude-code (default) | The Claude Code CLI |
| OpenAI Assistant | openai | The OpenAI HTTP API |
| Perplexity Assistant | perplexity | The Perplexity Sonar HTTP API |
Drop an Assistant card
Drag (or click) one of the three Assistant cards from the palette onto the Workspace. The card appears immediately. Its full record is persisted to the database the first time you open it for editing (or on its first run), so you can configure it before it ever runs.
Open the drawer
Double-click the card (or use its menu) to open the agent drawer. The drawer loads the Assistant’s real saved configuration before showing the editable tabs.
Configure and save
Edit fields across the drawer’s tabs, then click the single Save button in the footer bar to persist your changes (see Saving changes below).
The drawer has four tabs — Configure, Capabilities, Safety, and History — and in the current build all four are always visible. The tabs carry dormant tier gating (Safety and History are flagged for the Standard tier and above), but interface complexity is pinned to the Full tier and is not user-configurable, so nothing is ever hidden. See Settings for the tier story.
Saving changes
The drawer batches edits two different ways:
- The Configure and Safety tabs share one in-memory draft. Everything they edit — identity, model, permission mode, loop settings, agent teams, tools, scope paths — is persisted together by the single Save button in the footer bar, in one
PATCHto/api/agents/:id. The bar shows “Unsaved changes” while the draft is dirty and “All changes saved” after a successful write. Permission mode, loops, and the other Configure/Safety controls do not save on change — they save when you press Save. - The Capabilities tab (Skills, Connections, External Folders) and the History tab (Memory) save immediately to their own endpoints as you toggle, reorder, attach, or detach.
Name and Personality are required server-side. If either is empty, the Save button is disabled and the bar shows a validation message — because the whole Configure + Safety delta ships in one PATCH, an empty required field would reject the entire batch.
The Configure tab
The Configure tab merges the Assistant’s identity, model, and advanced controls into one scrolling panel.
Identity
| Field | What it does |
|---|---|
| Name | Display name (up to 80 characters in the UI; the API allows up to 100). |
| Avatar | Optional image URL shown on the card and drawer header. Falls back to a bot icon. |
| Description | A short summary of what the Assistant does (up to 300 characters). |
| Personality (persona) | The free-text system prompt that defines how the Assistant behaves (up to 25,000 characters in the UI; the server enforces only a non-empty value, with no upper limit). If you leave it blank when a card is first persisted, RondoFlow generates a minimal one like You are <name>. |
| Purpose | A category — General, Writing, Coding, Analysis, Chat, Review, Research, Creative, or Data. It drives the recommended model. |
The Personality is the heart of the Assistant. It becomes the base system prompt the model reads on every run, so be specific about role, tone, and constraints.
Model & provider
Every Assistant runs on a provider, chosen by which palette card you dropped (it cannot be changed in the drawer). See AI Providers for the full comparison.
Claude Code
The default provider (claude-code) spawns the Claude Code CLI. You pick a model tier, which maps to a concrete model at run time:
| Tier | Model ID |
|---|---|
| Opus | claude-opus-4-5 |
| Sonnet | claude-sonnet-4-5 |
| Haiku | claude-haiku-4-5 |
If you leave the model unset, RondoFlow picks a tier from the Purpose; if there’s no purpose either, it defaults to Sonnet. (Every purpose except Analysis and Review also resolves to Sonnet, so Sonnet is the practical default.) The Configure tab shows a recommended tier with a reason.
There is also a Custom model id field below the tier picker. Enter any model identifier here and it overrides the tier, forwarded verbatim to the CLI’s --model flag. Picking a tier clears the custom id, and vice versa. See Claude Code.
Advanced controls
Below the model section, the same Configure tab exposes:
- Loop — repeat the Assistant until a stop criterion is met (see Loops).
- Agent Teams — allow this Assistant to coordinate with others during a run.
- Permission Mode — controls how much the Assistant can do without asking. The drawer’s radio group offers three of the four modes:
| Mode (drawer) | Behavior | CLI mapping |
|---|---|---|
| Default | Standard permission checks | default |
| Accept Edits | Auto-accept file edits, but not bash/git | acceptEdits |
| Full Access | Read, write, and run git/bash without prompts | bypassPermissions |
A fourth mode, Plan (plan), exists at the data and API level (AgentMode is plan | default | edit | full) but the drawer deliberately doesn’t offer it. When the drawer doesn’t touch it, an Assistant set to plan elsewhere keeps that mode — the unified Save only sends the fields you actually changed.
All Advanced controls are part of the Configure/Safety draft, so they persist when you click Save (not on change). Safety Rules can override the permission mode at run time — the most restrictive setting wins.
The Safety tab
The Safety tab controls allowed tools and scope paths for Claude Code Assistants. (For OpenAI/Perplexity Assistants this tab just notes that tools are managed in Configure.)
A Safety Level is a quick preset over the underlying tool set:
| Level | Effect |
|---|---|
| Cautious | No tools granted — requires approval for everything (empty allowlist). |
| Balanced | Pick exactly the tools you want from the checklist below. |
| Autonomous | Grant all tools (the * wildcard) — runs without approval prompts. |
In Balanced mode you check individual Claude Code tools: Read, Write, Edit, Bash, Glob, Grep, LS, WebFetch, WebSearch, and TodoWrite. These names are forwarded verbatim to the CLI’s --allowedTools, so they must match real tool identifiers.
Read, WebSearch, and WebFetch are an always-on baseline: the engine merges them into the resolved allowlist even when an Assistant narrows itself to a smaller set. If an Assistant has no configured tools at all, it falls back to a broader default allowlist — the ten tools above plus TodoRead (eleven in total) — rather than running with none.
Scope paths restrict the directories the Assistant should work within. Add absolute paths; they’re stored on the Assistant and used alongside External Folders.
The Capabilities tab
This tab attaches Skills, Connections, and External Folders. Everything here saves immediately to its own endpoint as you change it.
Skills
Skills are reusable instruction packs (a SKILL.md and optional MCP config). Each attached Skill carries two properties:
- Priority — drag to reorder. Lower numbers load first.
- Enabled — a per-Skill on/off toggle.
At run time, the engine appends each enabled Skill’s content to the system prompt, ordered by priority. Disabled Skills are skipped entirely.
Connections (MCP)
Connections are MCP servers that add external tools and data sources. Toggle a server on for the Assistant in this tab; the engine merges Connection configs (plus any Skill-provided MCP servers) when it starts the run.
External Folders
Attach host directories the Assistant may read and write. They share the same priority/enabled model as Skills; the highest-priority folder becomes the Assistant’s working directory. See External Folders.
The History tab
The History tab hosts:
- Memory — a per-Assistant key/value store, gated by the Assistant’s memory toggle. When enabled, saved memories are injected into the system prompt under an “Agent Memory” heading. See Memory. Memory edits save immediately.
- Conversations (sessions) — past Conversations with this Assistant.
The memory toggle gates only the Assistant’s own memories. Workspace-shared memory is injected whenever workspace-scoped rows exist, regardless of this toggle — see How the system prompt is composed.
Other flags
- Favorite — pin the Assistant for quick access from the top bar. Toggle it via
isFavorite. - Facilitator (moderator) — mark the Assistant as a Facilitator so it can moderate Discussions. Toggle it via
isFacilitator; the agents list can be filtered to Facilitators only.
How the system prompt is composed
When an Assistant starts (the engine’s spawn), the prompt builder assembles its instructions in layers:
- Personality — the persona text, as the base system prompt.
- Memory — the Assistant’s own memories (only when its memory toggle is on) plus any workspace-shared memory, appended under their own headings. Workspace memory is injected whenever workspace-scoped rows exist, independent of the per-Assistant toggle.
- Skills — each enabled Skill’s
SKILL.mdcontent, in priority order, appended as a separate system-prompt section. - Workspace context — resources, environment, and directories from the Workspace and External Folders.
- Model & tools — the resolved model ID, allowed tools, permission mode, and any Safety Rule overrides.
API-provider Assistants reuse the same Personality + Skills system prompt but skip the Claude-CLI-specific layers (tool allowlist, MCP, external folders, Claude credentials).
Assistants in data workflows
Assistants are the only nodes that do model work, but a Workspace also has data-pipeline cards that wrap around them — Output, Email, Condition, Structure, and Save to DB. They consume an Assistant’s output to write files, send mail, route between branches, or persist structured data. See Data Nodes for how to connect them.
The Assistants API
Assistants are managed under /api/agents. Responses use the standard { success, data?, error?, meta? } envelope.
| Method | Path | Purpose |
|---|---|---|
GET | /api/agents | List Assistants. Add ?facilitator=true to list only Facilitators. |
GET | /api/agents/:id | Get one Assistant with its skills, policies, memories, and external folders. |
POST | /api/agents | Create an Assistant. |
PATCH | /api/agents/:id | Update fields (identity, model, tools, loop, favorite, facilitator, …). |
DELETE | /api/agents/:id | Delete an Assistant. |
POST | /api/agents/:agentId/skills/:skillId | Attach a Skill (upserts priority and enabled). |
DELETE | /api/agents/:agentId/skills/:skillId | Detach a Skill. |
POST | /api/agents/:agentId/mcp/:mcpServerId | Assign a Connection (MCP server). |
DELETE | /api/agents/:agentId/mcp/:mcpServerId | Unassign a Connection. |
The skills attach endpoint upserts the full (priority, enabled) pair. When you change just one field, send the other too — otherwise it resets to its schema default (priority: 0, enabled: true).
provider defaults to claude-code. For openai and perplexity, providerConfig is required on create — see the API reference for the full request schemas.