Algorithm Overview

Each algorithm type determines how the system selects an agent for a task. The algorithm is configured as part of the assignment configuration and applies to all tasks processed while that configuration is active.

Algorithm Type	Summary	Best For
manual	Dispatcher manually picks the agent	Small teams, complex scenarios
nearest	Assigns to the closest available agent	General use (default)
load-balanced	Distributes tasks evenly across agents	Fairness, equal workload
predictive	ML-based using historical data	Optimized ETAs, large fleets
one-by-one	Sequential offering with auto-retry	Gig-style operations
zone-based	Assigns based on geographic zones	Regional coverage, territories

Manual

With the manual algorithm, no automatic assignment occurs. Tasks remain in AWAITING_ASSIGNMENT until a dispatcher explicitly selects an agent from the dashboard.

Aspect	Details
Algorithm Type	manual
Automation	None — fully human-driven
Agent Selection	Dispatcher picks from a list of all available agents
Retry on Rejection	Dispatcher must manually reassign
Use Case	Small teams, tasks requiring special handling, or when algorithmic assignment is not desired

Nearest

The nearest algorithm assigns the task to the closest available agent based on GPS distance. This is the default algorithm and the simplest automatic option.

Aspect	Details
Algorithm Type	nearest
Selection Criteria	Straight-line (haversine) distance from agent's current GPS position to the task pickup location
Search Radius	Limited by maxSearchRadiusMeters (configurable, 100 to 100,000 meters)
Tie-Breaking	If multiple agents are equidistant, the agent with fewer active tasks is preferred
Requirements	Agents must have GPS tracking enabled and be sharing their location
Use Case	General-purpose delivery operations where minimizing travel time is the priority

Load-Balanced

The load-balanced algorithm distributes tasks as evenly as possible across all available agents. It prioritizes fairness over proximity.

Aspect	Details
Algorithm Type	load-balanced
Selection Criteria	The agent with the fewest currently active tasks (in ASSIGNED, ACCEPTED, or IN_TRANSIT status)
Search Radius	Still respects maxSearchRadiusMeters — only agents within range are considered
Tie-Breaking	When agents have equal load, the nearest agent is selected
Use Case	Operations where workload fairness is critical — ensures no single agent is overwhelmed while others are idle

Predictive

The predictive algorithm uses machine learning models to optimize assignment based on historical performance data, traffic patterns, and estimated time of arrival (ETA).

Aspect	Details
Algorithm Type	predictive
Selection Criteria	Multi-factor scoring: historical delivery time, agent performance rating, predicted traffic conditions, and estimated ETA
Data Requirements	Requires sufficient historical data (completed tasks) for the ML model to produce accurate predictions
Search Radius	Respects maxSearchRadiusMeters
Use Case	Large fleets with extensive delivery history where optimizing delivery time and success rate is the primary goal

One-by-One

The one-by-one algorithm offers the task to agents sequentially, one at a time, with automatic retry if an agent rejects or does not respond within the timeout period.

Aspect	Details
Algorithm Type	one-by-one
Selection Criteria	Agents are ranked (typically by distance), then offered the task one at a time in order
Retry Behavior	If the current agent rejects or times out, the task is automatically offered to the next agent in the queue
Search Radius	Respects maxSearchRadiusMeters
Reference	US001 — Sequential Assignment with Auto-Retry
Use Case	Gig-economy style operations, ride-hailing patterns, or when you want agents to explicitly opt in to each task

Zone-Based

The zone-based algorithm assigns tasks based on predefined geographic zones (delivery territories). Each agent is assigned to one or more zones, and tasks are routed to agents whose zone covers the task's pickup or delivery location.

Aspect	Details
Algorithm Type	zone-based
Selection Criteria	The task's location is matched against geographic zone boundaries; only agents assigned to the matching zone are considered
Within-Zone Selection	Among agents in the matched zone, the nearest or least-loaded agent is selected (configurable)
Prerequisites	Zones must be defined and agents must be assigned to zones (see Tracking & Zones)
Use Case	Operations with defined delivery territories, regional teams, or franchise-style setups where agents should only handle tasks in their area

Algorithm Comparison

Feature	manual	nearest	load-balanced	predictive	one-by-one	zone-based
Automatic	✗	✓	✓	✓	✓	✓
Uses GPS	✗	✓	✓	✓	✓	✓
Considers Load	✗	Tie-break	✓ Primary	✓	✗	Configurable
ML/Historical Data	✗	✗	✗	✓	✗	✗
Requires Zones	✗	✗	✗	✗	✗	✓
Auto-Retry	✗	✓	✓	✓	✓ Built-in	✓
Complexity	Low	Low	Medium	High	Medium	Medium

Configuration Fields

Every assignment configuration uses the following fields, regardless of the algorithm type. These are configured through the dashboard or API.

Field	Type	Required	Description
name	String	Yes	A human-readable name for this configuration (e.g., "Default Nearest", "Downtown Zone Config")
algorithmType	Enum	Yes	One of: manual, nearest, load-balanced, predictive, one-by-one, zone-based
enabled	Boolean	Yes	Whether automatic assignment is enabled for this configuration
isActive	Boolean	Yes	Whether this is the currently active configuration (only one per organization)
maxSearchRadiusMeters	Number	No	Maximum distance (in meters) to search for eligible agents. Range: 100 to 100,000. Default: 10000
config	JSON	No	Algorithm-specific configuration options as a JSON object. Contents vary by algorithm type.

Choosing the Right Algorithm

I have a small team (fewer than 10 agents)

Start with manual or nearest. Manual gives you full control; nearest provides simple automation with minimal configuration.

I want fair workload distribution

Use load-balanced. It ensures no single agent gets overwhelmed while others sit idle. Within the search radius, the agent with the fewest active tasks is always picked first.

I have a large fleet and historical data

Consider predictive. It uses ML models trained on your historical task data to predict the best agent based on ETA, traffic, and past performance. Requires sufficient data to be effective.

I want agents to accept/decline individually

Use one-by-one. Tasks are offered sequentially — if an agent declines, the next closest agent gets the offer automatically. This is ideal for gig-economy style operations.

My agents cover specific geographic areas

Use zone-based. Define delivery zones on the map, assign agents to zones, and the system will only consider agents whose zone covers the task location.

Next Steps

• Set up your assignment configuration in the dashboard
• Review the full assignment flow to understand how tasks move through statuses
• Configure delivery zones if using zone-based assignment