Building an Orchestration

An orchestration is a group of agents wired into a directed graph. Use one when a process needs multiple agents, handoffs, or event-driven work that should move through a known path.

Members and edges reference agents by slug, not ID; the CLI resolves each slug to the agent linked in its agents/<slug>/ folder. The file does not substitute ${VAR} placeholders.

What orchestrations are for

• Multi-agent work: Split research, drafting, review, and follow-up across specialized agents.
• Handoffs: Pass structured context from one agent to another.
• Event-driven processes: Start from triggers and route work through the right agents.
• Reusable systems: Save a proven setup as a template for future teams or projects.

What to connect

Connect agents when one agent's output should become another agent's input. Connect triggers when the orchestration should start from an app event or schedule. Describe each edge so the handoff is clear.

Cloudflare file handoffs

Handoffs to Cloudflare agents can include workspace files. Brainbase prepares the recipient's sandbox, copies the attachments, and then starts the recipient's task. You do not need to send a separate message to start its sandbox first.

Best practices

• Make each agent responsible for one testable, evaluatable task so you can improve the graph one step at a time.
• Give each agent one clear role in the orchestration.
• Use edge descriptions to explain what context should be passed forward.
• Test one handoff at a time before adding external triggers.
• Pass the summary, artifact, or decision the next agent needs instead of the full history.