---
title: "Add and configure agents"
description: "Three ways to add agents to the canvas, every field in the Agent Config popup, and when to fill which."
slug: guides/building-workflows/add-and-configure-agents
section: guides
subsection: building-workflows
canonical_url: https://cerevisor.com/docs/guides/building-workflows/add-and-configure-agents
last_verified: 2026-05-18
last_verified_version: "1.2.0"
updated_at: 2026-05-18T15:08:18.053416+00:00
---

## Adding an agent

Three ways. Pick whichever feels fastest in the moment.

### 1. Drag from the Agent Palette

Open the palette from the left edge of the canvas (the icon strip). Drag any role card onto the canvas. Release where you want the agent. Cerevisor places it in the nearest column.

### 2. Right-click the canvas

Right-click any empty area. Choose **Add Agent → [Role]**. The agent appears at your cursor position.

### 3. Press 1–9 or 0

Pressing a number key enters **placement mode** for the N-th role in your palette order. Your cursor becomes a ghost of the agent. Click anywhere to place. Press Escape (or right-click) to cancel.

This is the fastest path once you know your palette order. Reorder roles in **Settings → Agents** to put your favorites at 1 and 2.

### 4. Drag a Custom Agent template

If you've saved a custom agent template (see [Reference → Agent roles → Custom Agent](../../reference/agent-roles.md)), drag the template card from the palette onto the canvas. It carries its saved skills, model, and instructions.

## Configuring an agent

Click the agent's name or role badge to open the **Agent Config** popup. Every field below is in that popup, top to bottom.

### Name

The agent's display name on its card. Plain text. Choose something specific, "Senior researcher" beats "Researcher 2" for any workflow with more than one agent of the same role.

### Role (read-only)

The role badge. You set this when you added the agent; to change it, delete the agent and add a new one with the role you want. (We don't allow in-place role swaps because the role drives smart defaults that you may have customized.)

### Role description

A textarea. Free-form text describing what kind of agent this is. The default is the role's stock description; edit it to add specifics. Example:

> A researcher specialized in EU funding programs (Horizon Europe, EIC, Eurostars). Knows the eligibility quirks and reporting requirements. Cross-checks call deadlines on the official Funding & Tenders portal.

Goes into the agent's system prompt.

### Instructions

A textarea. The most important field. This is where you tell the agent what to do *in this specific workflow*.

Good instructions:

- Are concrete about the goal.
- Specify the input the agent will receive (from upstream agents or workflow input).
- Specify the output the agent should produce.
- Mention any constraints (length, format, sources).
- Mention any tools the agent should prefer (e.g. "use the `recency-research` skill").

Bad instructions: "Do research." (Too vague: the agent will produce generic output.)

### Output definition

A prose textarea, plus optional structured fields.

The **prose** describes what the output should look like in natural language:

> A 600-word markdown blog post with a title, a one-sentence summary line at the top, and 3-4 H2 sections. Tone: matter-of-fact, second-person, no hype. Include inline source citations.

Optional **structured fields**:

- **Required headings**: chip picker. Agent's output must include these H2 sections.
- **Min words**: integer. Agent's output must hit this length.
- **Deliverables**: chip picker. Specific items the agent must produce (e.g. "executive summary", "data table", "next steps").

These structured fields drive Cerevisor's output validation. If the agent's output doesn't include a required heading, the harness re-runs the agent with the missing item flagged.

### Skills

The hexagonal slots near the top of the popup (also visible on the card). Up to 6 skills per agent.

Drag skills from the Skills panel into a slot, or click an empty slot to open the picker. Click an equipped skill to remove it.

See [Working with Skills → Browse and assign skills](../working-with-skills/browse-and-assign-skills.md).

### Provider & model

A chip-style picker showing the resolved provider and a model dropdown.

By default, the agent inherits the workflow's default provider. Pick a chip to override. Pick the **Default** chip to revert to inheritance.

The model dropdown lists models available on the chosen provider. Pick **(auto)** to let the orchestrator's model router decide based on your role + subagent type + provider's catalog.

See [Providers → Per-agent overrides](../providers/per-agent-overrides.md).

### Thinking mode (if model supports)

Toggles extended thinking on models that support it (Anthropic Opus 4+, Sonnet 4+, and Haiku 4.5+ via the `anthropic-budget` surface, plus Gemini reasoning models via `thinkingBudget`, and always-on reasoners like DeepSeek R1, Qwen QwQ-32B, and `*-thinking` variants on OpenAI-compatible endpoints). Off by default; flip on for complex reasoning tasks where the latency cost is worth it.

### Subagent type

Dropdown: **explore / plan / bash / general-purpose / auto**.

Drives the default toolset and the agent's permission profile. See [Reference → Agent roles](../../reference/agent-roles.md) for what each type does.

### Allowed tools

Multi-select chips of every available tool: `read`, `write`, `edit`, `bash`, `glob`, `grep`, `web-search`, `web-fetch`, and any MCP tools you've added.

Defaults follow the subagent type. Override per agent, e.g. you might give a "Researcher" agent `web-search` but explicitly remove `bash`.

### Search provider

Dropdown: **Default / None / Tavily / Perplexity / Linkup**.

Picks which backend the `web_search` tool uses for this agent. Default inherits from the workflow setting. None disables web search entirely for this agent.

### Input files & output files

Drag markdown files from the Markdown panel into the **INPUT** (left) or **OUTPUT** (right) drop zone. See [Attach markdown files](./attach-markdown-files.md).

### Fallback strategy

Dropdown: **retry-once / skip-and-continue / ask-user / use-default**.

What the orchestrator does if this agent fails. Default is `retry-once`. For agents whose output is optional, prefer `skip-and-continue`. For agents whose failure should pause the workflow, use `ask-user`.

### Fallback instructions

Textarea. What the agent should output if it fails, or what the orchestrator should pass downstream as a placeholder. Used when `fallbackStrategy` is `use-default`.

### Context notes

Textarea. Free-form notes that get injected into the agent's system prompt as additional context. Use for one-off "remember that the user prefers dollars over euros" guidance you don't want in your global memory.

### Save as Template

Bottom-left button. Saves the agent's current config as a reusable Custom Agent template. The template appears in the palette and in **Settings → Agents → Custom Agents**.

### Delete Agent

Bottom-left button (next to Save as Template). Removes the agent and any connections that touched it. Confirms first.

### Done

Bottom-right. Closes the popup and flushes all pending edits.

## Editing multiple agents at once

Select multiple agents (Shift-click or drag a marquee). Most agent operations (Delete, Duplicate, Move to Wave) act on the whole selection.

You **cannot** open the Agent Config popup with multiple agents selected, config is per-agent.

## Smart defaults that aren't hidden

Cerevisor auto-fills these based on the role you picked:

- **Subagent type**: see the table in [Reference → Agent roles](../../reference/agent-roles.md).
- **Model preference**: same table.
- **Accent color**: used for the role badge and connection edges.
- **Tools**: defaults follow subagent type.

Anything you change in the Agent Config popup overrides these. The defaults exist so a one-click "Add Researcher" agent is useful immediately without configuration.