Multi-agent workflow

Spawn a peer agent and watch the two coordinate via peer messaging on the canvas.

Alumia is flat: any agent can message any other agent in the same project. There is no parent-child blocking, no central coordinator. This guide gets you to a two-agent flow you can watch happen live.

1. Open a project

Open the project you used in Build your first agent, or create a fresh one from /<orgSlug>/lab. The canvas needs to be open — peer activity surfaces there.

2. Confirm the originator agent has the peer tools

In /<orgSlug>/agents, open your agent and verify these tools are enabled:

spawn_agent — create a new peer on the fly.
message_agent — send a message to a peer in the same project.
check_messages — read replies addressed to this agent.
list_agents — see who else is running in the project.

These are built-in. If you removed them, re-enable and save.

3. Ask the agent to recruit a peer

Back in the lab, send a prompt that forces the spawn. For example:

"Spawn a research peer named Atlas with a system prompt focused on web research and citations. Once it's up, ask Atlas to find three primary sources on the 1666 Great Fire of London and summarise each in two sentences."

What happens next:

The originator calls spawn_agent with the requested name and system prompt. A new session appears on the canvas as a second agent node.
The originator calls message_agent to hand off the task to Atlas.
Atlas runs in its own session — its own context, its own model. It works in parallel; the originator does not block.
When Atlas has results, it calls message_agent back to the originator.
The originator calls check_messages, picks up the reply, and continues its turn.

You can watch all of this live: each tool call shows up on its agent's session, and message envelopes render as edges between the two nodes.

4. Read the canvas

The canvas shows what each agent is doing right now — the active tool, the message it just sent, the block it just wrote. If Atlas writes findings to a document block, that block renders as a node you can click into.

5. Persist the peer (optional)

spawn_agent creates an ephemeral peer for that project session. If you want Atlas around for next time, ask the originator to call create_agent instead — that persists Atlas to /<orgSlug>/agents so you can pick it from the prompt bar dropdown later.

Patterns that work

Researcher → writer → reviewer. Three peers, no coordinator. The writer messages the reviewer when the draft is done.
Fan-out. The originator spawns N peers in parallel, each on a slice of the problem, then aggregates their replies via check_messages.
Long-running specialist. Persist a peer with create_agent and message it from anywhere in the project later.