Skip to main content
Swarm Type: AgentRearrange

Overview

The AgentRearrange swarm type runs your agents in the order you define with rearrange_flow. You can reorganize how agents pass work to one another, mixing sequential handoffs and parallel steps, without changing the agents themselves. The flow is fixed for the request: nothing reassigns roles or adapts the order while the swarm runs. Key features:
  • Explicit Flow Control: rearrange_flow sets exactly which agents run, in which order
  • Sequential and Parallel Steps: -> hands work to the next step, and a comma runs agents in parallel within a step
  • Reorganize Without Rewriting: Change the pipeline by editing the flow string, not the agents
  • Real Synthesis Steps: An agent at the end of the flow receives the earlier agents’ outputs

Architecture

The shape comes from rearrange_flow. Above is "Researcher -> Writer, Editor": -> is a handoff to the next step, and a comma runs agents in parallel within the same step.

Use Cases

  • Dynamic project management with changing requirements
  • Adaptive content creation workflows
  • Performance optimization in multi-agent systems
  • Flexible task allocation based on agent strengths

API Usage

The AgentRearrange swarm type requires the rearrange_flow parameter. It is a string that defines how tasks flow between agents by agent_name: use -> for sequential handoffs and commas for agents that run in parallel within the same step (e.g. "Researcher -> Writer, Editor"). Requests without rearrange_flow are rejected with a 400 error, and so is a flow that names an agent that isn’t in agents: every name in the flow must be the exact agent_name of one of the agents (e.g. 400 “rearrange_flow names [‘Reviewer’], which match no agent_name in ‘agents’”).

Basic AgentRearrange Example

Example Response:

Best Practices

  • Spell every name in rearrange_flow exactly as the agent’s agent_name
  • Put agents that can work independently in the same step, separated by commas
  • End the flow at a synthesizer agent when you want one combined answer
  • Ideal for custom pipelines mixing sequential and parallel stages