Migrating to SwarmForge v5

SwarmForge v5 is a major release that makes the swarm graph the single source of routing truth. If you upgrade from v4.x, read this page before deploying.

Upgrade

pip install --upgrade "swarmforge>=5.0.0"

If you use the FastAPI transport:

pip install --upgrade "swarmforge[api]>=5.0.0"

Breaking changes

1. Declared edges only

The runtime no longer invents routes. These implicit behaviors from v4 are removed:

• automatic return to the calling parent agent
• automatic fallback route back to the entry node

Only edges declared in your graph are routable. If a specialist must return to the entry router or hand off to another specialist, declare that edge in sub_agents or edges.

Migration helper for graphs that relied on implicit return-to-entry behavior:

swarm = swarm.with_return_edges()

2. Stricter behavior_config validation

Invalid values in SwarmNodeBehaviorConfig now raise a clear ValueError naming the field, bad value, and allowed set. v4 silently reset unknown enum values to defaults.

Validate configs during authoring or tests before deployment.

3. required_variables enforced on every declared route

Handoffs always resolve a declared edge. Missing edges are rejected, and required_variables are checked for every valid transfer.

4. Evaluation path-finding matches runtime reachability

Scenario feasibility no longer assumes an implicit reroute through the entry node. Paths such as billing -> triage -> faq require an explicit billing -> triage edge.

5. Shared constants for runtime identifiers

Import named constants instead of matching raw strings:

from swarmforge.swarm import HANDOFF_TOOL_NAME, EVENT_HANDOFF, EVENT_DONE

See swarmforge.swarm.constants for the full set.

6. Stricter graph validation

validate_swarm_definition(...) now also rejects:

• duplicate node id values
• nodes unreachable from the entry node

Authoring updates

• Generated swarms must declare return edges explicitly. See META_PROMPT_SWARM in swarmforge.authoring.
• /generate_edge is available as a skill for authoring individual handoff edges.
• Runtime handoff policy is centralized in swarmforge.swarm.prompting and references the real entry node name instead of hardcoded "triage".

Suggested migration checklist

1. Upgrade to swarmforge>=5.0.0.
2. Audit multi-agent graphs for specialists that hand back to entry or cross-specialist without declared edges.
3. Run swarm.with_return_edges() or add explicit return edges where needed.
4. Re-run evaluation scenarios that assumed implicit reroute via the entry node.
5. Replace raw string checks for handoff tool names and stream events with swarmforge.swarm.constants.

Need help?

• Create Your First Multi-Agent Swarm
• Authoring
• Orchestration