---
title: "Connect agents"
description: "Drawing connections between agents, the four handoff formats, and how smart auto-connect works."
slug: guides/building-workflows/connect-agents
section: guides
subsection: building-workflows
canonical_url: https://cerevisor.com/docs/guides/building-workflows/connect-agents
last_verified: 2026-05-18
last_verified_version: "1.2.0"
updated_at: 2026-05-18T15:08:18.053416+00:00
---

A connection is a directed edge from one agent to another. It tells the orchestrator: "after the source finishes, the target reads its output and runs next."

## Drawing a connection

Hover over an agent. Two small handles appear on its left and right edges. Click and drag from the right edge of the source agent to the left edge of the target. A connection line draws between them.

Connections are always **left-to-right**; they imply ordering. If you try to draw a connection going backward, Cerevisor blocks it. (Loops are a separate connection type, see [Control flow](./control-flow-conditions-loops-gates.md).)

## Smart auto-connect

By default, when you add an agent to a new column, Cerevisor automatically wires every agent in the previous column to your new agent. This is **auto-connect**, and it works because most workflows want every upstream agent to feed every downstream one in the next wave.

Auto-connections render with **dashed lines**. Manual connections are **solid**.

If you draw a manual connection between two agents that auto-connect would have made, your manual wire wins (the dashed line disappears).

You can disable auto-connect per workflow in **Settings → Workflow → Auto-connection exclusions** by checking off roles you never want auto-wired.

## Handoff formats

Click a connection (or double-click) to open the **Connection Config** popup. The most important field is **Handoff format**:

| Format | What downstream sees |
|---|---|
| **Summary** | A short LLM-generated summary of the upstream agent's output. Useful when the full output is long and you only need the gist. |
| **Structured JSON** | The upstream output coerced into a JSON schema you define in **Handoff schema**. Use when the downstream agent needs specific fields. |
| **File reference** | The upstream agent's `outputFiles[]` — by name, not content. The downstream agent reads them via the `read_file` tool. Useful when output is large; keeps context lean. |
| **Full output** | The upstream agent's complete output, verbatim. The default. Use when downstream needs everything. |

The right format depends on context budget. Long workflows with chatty agents benefit from Summary or File reference; short workflows can stick with Full output.

## Data description

A free-text field on the connection. Describes what data flows over this edge. The text is included in the generated prompt so downstream agents understand the intent. Example: "Vetted candidate sources with confidence scores."

You don't have to fill it. Cerevisor generates a sensible default from the source agent's output definition.

## Selecting and editing connections

- **Click** an edge to select it.
- **Shift-click** to multi-select.
- **Double-click** to open Connection Config.
- **Right-click** for the connection context menu (Configure / Flow Type / Delete).
- **Delete / Backspace** with edges selected removes them.

## Auto-connection patterns

Three common patterns the harness handles automatically:

1. **One-to-many fan-out:** one upstream agent feeds N downstream agents in the next column. All N start in parallel.
2. **Many-to-one fan-in:** N upstream agents feed one downstream. The downstream waits for all N to finish, then runs.
3. **All-to-all:** N upstream, M downstream. Each downstream gets all N upstream outputs.

You don't need to draw these manually, auto-connect produces them. Manual wires let you carve exceptions (e.g. "Reviewer A only reads from Researcher 1, not Researcher 2").

## When you'd disable auto-connect

For a workflow where each column should produce siloed outputs that the next column picks from selectively, turn off auto-connect for the relevant roles in **Settings → Workflow**. Then draw manual wires.

## Connection colors

Connections inherit their color from the source agent's role accent. A connection from a Developer (emerald) → Reviewer (violet) draws an emerald-to-violet gradient. The color tells you at a glance which role originated the data flowing over the edge.